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TERMS  AND  CONDITIONS  OF  SALE  AND  LICENSE  OF  TANDY  COMPUTER  EOUIPMpNT  ANB 
SOFTWARE- PURCHASED  FROM  RADIO  SHACK  COMPANY-OWNED  COMPUTER  CENTERS,  RETAIL 
STORES  AND  RADIO  SHACK  FRANCHISEES  OR  DEALERS  AT  THEIR  AUTHORIZED  LOeATlQNS 

USA  LIMITED  WARRANTY 

I.  CUSTOMER  OBLIGATIONS 

A.  CUSTOMER  assumes  lull  responsibility  that  this  computer  hardware  purchased  (the  "Equipment"),  and  any 
copies  ol  software  included  with  the  Equipment  or  licensed  separately  (the  "Software")  meets  the  specifications, 
capacity,  capabilities,  versatility,  and  other  reQuirements  of  CUSTOMER. 

B.  CUSTOMER  assumes  full  responsibility  for  the  condition  and  effectiveness  of  the  operating  environment  in  which 
the  Equipment  and  Software  are  to  function,  and  for  its  installation. 

II.  LIMITED  WARRANTIES  AND  CONDITIONS  OF  SALE 

A.  For  a  period  of  ninety  (90)  calendar  days  from  the  date  of  the  Radio  Shacl<  sales  document  received  upon 
purchase  of  the  Equipment  RADIO  SHACK  warrants  to  the  original  CUSTOMER  that  the  Equipment  and  the 
medium  upon  which  the  Software  is  stored  is  Iree  Irom  manufacturing  defects.  This  warranty  Is  only  applicable 
to  purchases  of  Tandy  Equipment  by  the  original  customer  from  Radio  Shack  company-owned  computer 
centers,  retail  stores,  and  Radio  Shack  franchisees  and  dealers  at  their  authorized  locations.  The  warranty  is 
void  if  the  Equipment  or  Software  has  been  subjected  to  improper  or  abnormal  use.  If  a  manufacturing  defect  is 
discovered  during  the  stated  warranty  period,  the  defective  Equipment  must  be  returned  to  a  Radio  Shack 
Computer  Center,  a  Radio  Shack  retail  store,  a  participating  Radio  Shack  Iranchisee  or  a  participating  Radio  Shack 
dealer  for  repair,  along  with  a  copy  of  the  sales  document  or  lease  agreement.  The  original  CUSTOMER'S  sole  and 
exclusive  remedy  in  the  event  of  a  defect  is  limited  to  the  correction  oi  the  deled  by  repair,  replacement,  or 
refund  of  the  purchase  price,  at  RADIO  SHACK'S  election  and  sole  expense  RADIO  SHACI<  has  no  obligation  to 
replace  or  repair  expendable  items, 

B.  RADIO  SHACK  makes  no  warranty  as  to  the  design,  capability,  capacity,  or  suitability  for  use  of  the  Software, 
except  as  provided  in  this  paragraph.  Software  is  licensed  on  an  "AS  IS"  basis,  without  warranty.  The  original 
CUSTOMER'S  exclusive  remedy,  in  the  event  ol  a  Software  manufacturing  defect,  is  its  repair  or  replacement 
within  thirty  (30)  calendar  days  ol  the  date  ol  the  Radio  Shack  sales  document  received  upon  license  of  the 
Software.  The  defective  Software  shall  be  returned  to  a  Radio  Shack  Computer  Center,  a  Radio  Shack  retail  store, 
a  participating  Radio  Shack  franchisee  or  Radio  Shack  dealer  along  with  the  sales  document. 

C.  Except  as  provided  herein  no  employee,  agent,  franchisee,  dealer  or  other  person  is  authorized  to  give  any 
warranties  of  any  nature  on  behalf  of  RADIO  SHACK, 

D.  EXCEPT  AS  PROVIDED  HEREIN,  RADIO  SHACK  MAKES  NO  EXPRESS  WARRANTIES,  AND  ANY  IMPLIED 
WARRANTY  OF  MERCHANTABILITY  OR  FITNESS  FOR  A  PARTICUUR  PURPOSE  IS  LIMITED  IN  ITS  DURATION 
TO  THE  DURATION  OF  THE  WRIHEN  UMITEO  WARRANTIES  SET  FORTH  HEREIN. 

E.  Some  states  do  not  allow  limitations  on  how  long  an  Implied  warranty  lasts,  so  tin  aliove  limitaftmls)  mw  not 
apply  to  CUSTOMER, 

III.  UMITATION  OF  LIABILITY 

A.  EXCEPT  AS  PROVIDED  HEREIN.  RADID  SHACK  SHALL  HAVE  NO  LIABILITY  OR  RESPONSIBILITY  TO  CUSTOMER 
OR  ANY  OTHER  PERSON  OR  ENTITY  WITH  RESPECT  TO  ANY  LIABILITY.  LOSS  OR  DAMAGE  CAUSED  OR 
ALLEGED  TD  BE  CAUSED  DIRECTLY  OR  INDIRECTLY  BY  "EQUIPMENT"  OR  'SOFTWARE"  SOLD,  LEASED, 
LICENSED  OR  FURNISHED  BY  RADIO  SHACK,  INCLUDING,  BUT  NOT  LIMITED  TO,  ANY  INTERRUPTION  OF 
SERVICE,  LOSS  OF  BUSINESS  OR  ANTICIPATORY  PROFITS  OR  CONSEQUENTIAL  DAMAGES  RESULTING  FROM 
THE  USE  OR  OPERATION  OF  THE  "EQUIPMENT"  OR  "SOFTWARE."  IN  NO  EVENT  SHALL  RADIO  SHACK  BE 
LIABLE  FOR  LOSS  OF  PROFITS,  OR  ANY  INDIRECT,  SPECIAL,  OR  CONSEQUENTIAL  DAMAGES  ARISING  OUT  OF 
ANY  BREACH  OF  THIS  WARRANTY  OR  IN  ANY  MANNER  ARISING  OUT  OF  OR  CONNECTED  WITH  THE  SALE, 
LEASE,  LICENSE,  USE  OR  ANTICIPATED  USE  OF  THE  "EQUIPMENT"  OR  "SOFTWARE." 
NOTWITHSTANDING  THE  ABOVE  LIMITATIONS  AND  WARRANTIES,  RADIO  SHACK'S  LIABILITY  HEREUNDER  FOR 
DAMAGES  INCURRED  BY  CUSTOMER  OR  OTHERS  SHALL  NOT  EXCEED  THE  AMOUNT  PAID  BY  CUSTOMER  FOR 
THE  PARTICUUR  "EQUIPMENT"  OR  "SOFTWARE"  INVOLVED. 

B.  RADIO  SHACK  shall  tiot  be  llalile  for  aiqr  daMSK  cattsed  by  delay  In  delivering  or  fumisliing  Equlpniant  andAir 
Software. 

C.  No  action  arising  out  of  any  claimed  breach  of  this  Warranty  or  ttansactions  under  this  Warranty  may  be  braught 
more  than  two  (2)  years  after  the  cause  of  action  has  accrued  or  mora  than  four  (4)  years  alter  the  date  of  the 
Radio  Shack  sales  iiocument  for  the  Equipment  or  Software,  whichever  first  occurs. 

D  Some  states  do  not  allow  the  llroitatlon  or  exclusion  of  incidental  or  consequential  damages,  so  the  above 
limitation(s)  or  excluslon(s)  may  not  apply  to  CUSTOMER. 

IV.  SOFTWARE  LICENSE 

RADIO  SHACK  grants  to  CUSTOMER  a  non-exclusive,  paid-up  license  to  use  the  TANDY  Software  on  one  computer. 

subject  to  the  following  provisions 

A.  Except  as  otherwise  provided  in  this  Software  License,  applicable  copyright  laws  shall  apply  to  the  Software. 

B.  Title  to  the  medium  on  which  the  Soltware  is  recorded  (cassette  and/or  diskette)  or  stored  (ROM)  is  transferred  to 
CUSTOMER,  but  not  title  to  the  Software. 

C.  CUSTOMER  may  use  Software  on  a  multiuser  or  network  system  only  if  either,  the  Software  is  expressly  labeled 
to  be  for  use  on  a  multiuser  or  network  system,  or  one  copy  of  this  software  is  purchased  for  each  node  or 
terminal  on  which  Software  is  to  be  used  simultaneously, 

D.  CUSTOMER  shall  not  use,  make,  manufacture,  or  reproduce  copies  of  Software  except  for  use  on  one  computer 
and  as  Is  specifically  provided  in  this  Software  License.  Customer  is  expressly  prohibited  from  disassembling  the 
Software. 

E  CUSTOMER  is  permitted  to  make  additional  copies  of  the  Software  only  for  backup  or  archival  purposes  or  If 
additional  copies  are  required  in  the  operation  of  one  computer  with  tlie  Software,  but  only  to  the  eMt  the 
Software  ailot«/s  a  bacltup  copy  to  be  made.  However,  for  TRSIjOS  SofMare.  CUSTOMER  is  petlmttiii  to  li!W$a<9 
limited  number  of  additional  copies  for  CUSTOMER'S  own  use. 

F.  CUSTOMER  may  resell  or  distribute  unmodified  copies  of  the  Software  provided  CUSTOMER  tas  purchased  one 
copy  of  the  Software  for  each  one  sold  or  distributed.  The  provisions  of  this  Software  iieme  shall  aliSO  be 
applicable  to  third  parties  receiving  copies  of  the  Software  from  CUSTOMER. 

G.  All  copyright  notices  shall  be  retained  on  all  copies  ol  the  Software. 

V.  APPLICABILITY  OF  WARRANTY 

A.  The  terms  and  conditions  of  this  Warranty  are  applicable  as  between  RADIO  SHACK  and  CUSTOMER  to  either  a 
sale  of  the  Equipment  and/or  Software  License  to  CUSTOMER  or  to  a  transaction  whereby  Radio  Shack  sells  or 
conveys  such  Equipment  to  a  third  party  for  lease  to  CUSTOMER. 

B.  The  limitations  of  liability  and  Warranty  provisions  herein  shall  inure  to  the  benefit  of  RADIO  SHACK,  the  author, 
owner  and  or  licensor  of  the  Software  and  any  manufacturer  of  the  Equipment  sold  by  Radio  Shack. 

VI.  STATE  UW  RIGHTS 

The  warranties  granted  herein  give  the  original  CUSTOMER  specific  legal  rights,  and  the  original  CUSTOMER  may 
have  other  rights  which  vary  from  state  to  state.  4/B7 
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OS-9  Level  Two  Operating  System  (software): 
©  1986,  Microywe  ^sterns  Cocparatioii 

AU  Bights  Reserved. 

All  portions  of  this  software  are  copyrighted  and  are  the 
proprietary  and  trade  secret  information  of  Tandy 
Corporation  and/or  its  licensor.  Use,  reproduction  or 
publication  of  any  portion  of  this  material  without  the 
prior  written  authorization  by  Tandy  Corporation  is 
strictly  profaiibited. 

OS-9  Level  Two  Operating  System  (mandal): 
©  1986,  Tandy  Corporation. 
All  Ri^ts  Reserved. 

Reproduction  or  use  of  any  portiimi  Of  this  manual,  without 
express  written  permission  from  Tandy  Corporation  and/or 
its  licensor,  is  prohibited.  While  reasonable  efforts  have 
been  made  in  the  preparation  of  this  manual  to  assure  its 
accuracy,  Tandy  Corporation  assumes  no  liability 
resulting  from  any  errors  in  or  omissions  &om  this 
manual,  or  btm  tibe  use  of  the  information  contained 
herein. 

Tandy  is  a  registered  trademark  of  Tandy  Corporation. 

OS-9  is  a  trademark  of  Microware  Systems  Corporation. 

BASIC09  is  a  trademark  of  Microware  Systems 
Corporation  and  Motorola,  Inc. 
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Getting  Started 
With 
OS-9 


About  This  Manual 


Using  Your  OS-9  Handbook 

If  you  feel  that  starting  a  new  computer  operating  system  is  a 
"smey  business,"  relax.  This  handbook  is  designed  to  put  you  at 
ease  when  using  OS-9.  It  is  divided  into  two  parts — each  psurt  has 
a  different  purpose. 

What  is  in  Part  1 

"Part  1"  of  this  handbook  is  designed  to  show  you,  step  by  step, 
how  to  set  up  and  use  your  computer  with  OS-9.  Follow  the  steps 
as  they  are  described,  and  OS-9  is  your  obedient  servant.  The  few 
instructions  in  "Part  1"  are  all  that  many  OS-9  users  ever  need. 

What  is  in  Part  2 

"Part  2"  is  for  the  more  adventurous.  OS-9  has  an  extensive  rep- 
ertdre  of  commands  and  functions  to  create  and  manage  data  and 
to  make  mse  of  peripherals  (devices  you  can  connect  to  your  com- 
puter, saeh  as  mSk  dirfves  and  printers).  If  you  want  to  learn  more 
about  the  operating  system,  and  if  you  like  to  explore,  "Part  2"  is 
for  you.  You  learn  other  useful  OS-9  commands  that  prepare  you 
to  make  use  of  all  the  functions  and  commands  described  in 
OS-9  Commands. 


i 


Contents 


Part  1  /  What  You  Need  to  Know  About  OS-9 


Chapter  1    What  is  an  Operating  System?   .1-1 

Instructing  Your  Operatiof  System   1-1 

Using  Application  Prospiuns  and  Computer 

Languages   1-2 

Using  Peripherals  . .    1-3 

Why  Use  OS-9?  1-4 

How  Much  Do  You  Need  to  Know  About  OS-9?  . .  1-5 

Chapter  2   How  to  Start  and  Exit  Your  System  . .  .  2-1 

Booting  OS-9   2-2 

Rebooting  OS-9   2-3 

Exiting  OS-9   2-3 

Upper-  and  Lowercase  Characters  ..............  2-4 

OS-9  Error  Messages   . — ,2-4 

Chapter  3  What  ttm  Need  to  Know  to  Use 

Floppy  Drives   3-1 

Write  Protection  for  Diskettes   3-2 

Disk  Drive  Names     3-2 

MeJcing  Copies  of  Diskettes   3-3 

Earmatting  With  One  Disk  Drive   3-3 

Formatting  With  Two  Disk  Drives  .  3-4 

Using  the  Backup  Command  .3-5 

Making  Copies  With  One  Disk  Drive   ..... .3-5 

Making  Copies  With  Two  Disk  Drives  . . . . .  3-7 

Part  2  /  Organization,  Commands,  and  Keys 

Chapter  4   Files  and  Directories  4-1 

About  Files  ,   4-1 

About  Directories  ,  4-1 

Multiple  Directories   .4-4 

About  File  and  Directory  Names   .4-4 

Examples  of  Filenames  4-4 

About  Pathlists  .4-5 

Anonymous  Directory  Names  4-6 

About  Device  Nsunes    4-6 


Chapter  5    Commands  and  Keys  . . .   5-1 

Typing  Commands  5-1 

Editing  Comm&nds  .... .  .  ....  5-1 

Command  Parameters  5-2 

Using  Options   5-2 

Using  Commands  5-3 

Accessing  Commands  5-4 

Commands  from  Disk  , , » * . . , , , . , , ,  5-5 

Changing  the  Execution  Directory  , .  , .... , . . ...  .SS 

Changing  the  Data  Directory  . . . . , . , , , , . . , ,  „ , , ,  5-7 

Changing  System  Diskettes  . . , , , , . ,  5-7 

Video  Display  soA  K^bisfi  Ftections  5-8 

Special  Keys  5-8 

Chapter  6   OS-9  Toolkit   ,  6-1 

Viewing  Directories  6-1 

Creating  Directories   ,  ,  6-1 

Deleting  Directories   6-2 

Displaying  CmmA  Direeiwies  6-2 

Copying  Files  6-3 

Deleting  Files   6-4 

Renaming  Files  6-4 

Looking  Inside  Files   . . .  .6-5 

Loading  Command  Modules  Into  Memory  .  6-i 

Listing  the  Command  Modules  in  Memory   6-5 

Deleting  Modules  from  Memory   6-6 

Using  Other  Commands  6-6 

Chapter  7   Customizing  Your  System   7-1 

Creating  a  New  System  Diskette    7-1 

Monitor  Types   7-8 

Using  Windows   7-9 

Establishing  a  Window  ....  .  7-9 

Changing  Window  Colors   7-11 

Eliminating  a  Window   7-12 

Using  Startup  to  Establish  a  Window  7-13 


Index 


Parti 


What  You  Need  to  Know 
About  OS-9 


I 

'5 


9 


Chapter  1 


What  is  an  Operating  System? 


OS-9  is  a  disk  Operating  System  (that's  what  OS  stands  for).  An 
operating  system  is  a  group  of  programs  actinf  a$  at  m^^^: 
center  and  an  interpreter.  Using  your  instructions,  an  operating 
system  manages  the  computer's  working  circuits. 

In  fact,  thinking  of  OS-9  as  your  computer  manager  is  helpful. 
The  boss  (that's  you)  gives  orders.  OS-9  (the  managa-)  sees  they 
get  done. 

To  operate  OS-9  you  need  at  least  one  floppy  disk  drive  attached 
to  fmat  ctmputer.  08-9  !s  origiBally  conligured  to  recognize  two 
floppy  disk  drives.  Later,  this  handbook  describes  how  to  let  OS-9 
know  if  you  have  more  than  two  floppy  disk  drives,  or  if  you  have 
other  hardware  (printers,  modems,  hard  disks,  and  so  on)  y«u 
want  it  to  recognize. 

Instructing  Your  Operating  System 

You  give  your  commands  to  OS-9  by  typing  them.  Because  OB-9 
does  exactly  (and  only)  what  you  tell  it,  your  entries  must  be  pre- 
cise and  have  perfect  syntax  (spelling  and  form).  You  must  also  be 
sure  to  give  OS-9  every  detail  it  needs  to  perform  a  task. 

For  instance,  if  you  told  J&m  office  manager  to,  "Make  a  phone 
call,"  what  c£in  the  manager  do?  Obviously,  not  much  that  is 
helpful  to  you.  The  manager  must  know  who  to  call,  the  phone 
number,  and  what  to  say.  OS-9  is  the  same.  It  must  have  all  the 
details  before  it  can  carry  out  your  commands  properly. 

To  show  you  how  to  instruct  your  operating  system,  the  hand- 
book asks  you  to  type  charaet^s,  worfs,  and  lines  csa  ysitf  l^-^ 
board.  When  you  do,  you  are  issuing  commands  to  OS-9. 
Technically,  a  command  is  only  one  word  that  describes  the  action 
you  want  OS-9  to  perform.  A  command  line  is  a  command  witii  all 
of  its  qualifiers. 

In  this  manual,  command  lines  usually  contain  words  in  boxes, 
sueh  as  I  ENTER  |.  These  indicate  keys  that  you  press. 

The  manual  also  asks  you  to  press  key  sequences.  For  instance, 
when  asked  to  press  |  ctrl  |  (T),  hold  down  the  key  marked  CTRL, 
and  while  holding  down  |  ctrl  |,  press  [c]. 
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Characters  that  are  not  in  boxes  are  typed  individually.  For 
instance,  if  you  are  asked  to  type  the  command  line  format  /d0 

I  ENTER  I,  press  each  key  individually  ((I](l][l][l][S[T]n(7|[?] 

(T|  I  ENTER  I). 

If  you  make  a  mistake  while  typing,  use  Q  to  move  back  to  the 
mrw,  Thm  retype  that  portion  of  the  line. 

Using  Application  Programs  and 
Computer  Languages 

A  computer  application  is  a  program  designed  to  accomplish  spe- 
cific tasks.  Timrs  are  application  programs  to  help  you  write  let- 
ters or  documents  (word  processors),  keep  a  mailing  list  (data 
managers),  and  keep  financial  records  (accounting  packages). 
There  are  also  programs  to  help  you  study  for  a  test,  pLs^  a  game, 
play  music,  draw  a  picture,  and  much  more. 

Such  application  programs  usually  require  that  you  use  OS-9  to 
stEirt  your  computer.  A  few  appifoation  prograims  let  you  start 
directly  from  the  application  diskette.  Different  programs  can 
require  different  procedures,  and  you  should  check  your  applica- 
tion program's  documentation  for  specific  instructions. 

Application  programs  have  special  screen  displays  and  menus  to 
instruct  you,  or  that  require  you  to  perform  a  particular  action, 
such  as  press  a  key.  When  you  are  operating  from  an  application 
program,  that  program  passes  your  instructions  to  OS-9.  OS-9 
manages  the  computer's  operations  in  the  background,  and  its 
functions  are  invisible  to  you. 

You  can  also  use  computer  langm^^  to  w^itfi  your  own  applica- 
tion programs.  BASIC  is  a  language.  If  you  read  the  Color 
Computer  Disk  System  manual,  you  already  know  a  bit  about  it. 
There  are  languages  you  can  purchase  to  use  with  OS-9  to  cre- 
ate programs,  such  as  assembly  language,  Pascal,  C,  and 
BASIC-09. 

Like  application  programs,  each  language  has  its  ovra  startup 
method.  The  manuals  that  cosae  with  the  languages  tell  you  how 
to  get  them  running  on  your  Odm  Computer  8. 
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Using  Peripherals 

OS-9  lets  you  control  much  more  than  your  computer's  opera- 
tions. It  also  gives  you  control  over  other  hardware  devices  such  as 
dMc  drives,  a  printer,  modems,  windows,  other  termina.ls,  and  so 
an. 

Each  device  has  a  "System  Name,"  an  abbreviation  preceded  by  a 
slash  (/).  OS-9  can  only  recognize  a  device  if  you  tyTpe  its  name 
exactly  as  shown  below.  See  Chapter  7,  "Customizing  Your 
System"  for  information  on  how  to  tell  OS-9  what  devices  you 
want  it  to  handle. 

Slystem 

Name  Description  

/P  A  printer  connected  through  your  computer's  I^- 

232  port.  The  RS^32  pcjrt  is  a  m^l  pwfc,  and 
you  must  have  a  printer  with  a  serial  connection, 
such  as  the  Radio  Shack®  DMP  430. 

/Tl  A  data  terminal  or  another  computer  acting  as  a 

terminal,  connected  through  the  RS-232  port  of 
your  computer.  If  you  are  using  another  computer 
as  a  terminal,  it  must  run  a  terminal  program 
that  makes  it  perform  as  a  terminal. 

/T2  Another  data  terminal  or  another  computer  act- 

ing as  a  terminal,  connected  to  an  optional  RS- 
232  communications  pak  in  a  Multi-Pak  Inter- 
face. If  you  are  using  another  computer  as  a  ter- 
minal, it  must  run  a  terminal  program  that 
makes  it  perform  as  a  terminal. 

/T3  Another  data  terminal  or  another  computer  act- 

ing as  a  terminal,  connected  to  the  optional  RS- 
232  communications  pak  in  a  Multi-Pak 
Interface.  If  you  are  using  another  computer  as  a 
terminal,  it  must  run  a  terminal  program  that 
makes  it  perform  as  a  terminal. 

/Ml  A  modem  using  an  optional  300-baud  modem  pak 

in  the  optional  Multi-Pak  Interface.  A  modem 
allows  you  to  communicate  with  other  computers 
either  directly  or  over  phone  lines. 
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System 
Name 


De8cri|>itfoii 


/M2 


Another  modem  using  an  optional  300-baud 
modem  pak  in  the  optional  Multi-Pak  Interfece. 

A  floppy  disk  drive. 


/DO 


/Dl 


Another  floppy  disk  dcive 


AV,  AVI, 
AV2,  /W3 

AV4,  AV5 
AV6,  AV7 


Windows  that  you  can  establish  on  your  OS-9 
systeaa.  use  |  clear  |  to  page  among  windows 
you  ccmiSB.  See  "Using  Windows"  in  Chapter  7 
and  (X3-9  Windowing  System  Owner's  Manual  for 
information  on  creating  wimtows. 


Why  Use  OS-9? 


You  now  know  that  OS-9  is  an  operating  system  for  your  Color 
Computer.  You  might  also  have  heard  that,  in  the  w^orld  of  com- 
puter operating  systems,  OS-9  is  a  leader.  Perhaps  that  is  why  you 
bought  it.  OS-9  stands  out  for  several  reasons.  Some  of  its  strong 

•  2%  nmmgix^  eapabilities. 

xissts  '&sBcs^  one  pexsoo.  can 
vm  &e  mms  (ssmpsxter  at  the  saxne  time. 

•  Multi-tasking.  OS-9  can  handle  several  jobs  at  the  same 


•  Window  functions  that  let  you  divide  your  display  screens 
into  sections  in  which  you  can  have  one  or  more  opera- 
tions running,  all  at  the  same  time. 

•  Input/Output  capabilities.  OS-9  can  esmmunicate  with 
T%  axtii  jaoaitixc'S^  dilik  driveij  pfinleirs,  and  other 

•  A  s^iiiiitaM  i^fefM^e  {€  commands. 

•  ii^Mstteted  p*@gx^cmxaiiig  lanp^ipes. 

If  you  are  not  familiar  with  Sllch  terms  as  files,  multi-user,  multi- 
tasking, and  commands,  6eia%  Worry.  The  handbook  explains  these 
terms  and  more. 


time. 
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Progra^nIaer^  like  OS-9  becauge  of  its  powerful  features.  It  lets 
them  show  off  all  of  their  skills.  a  resalt,  another  OS-9  fea- 
ture is  the  wide  range  of  excellmt  programs  that  you  can  use 
with  the  system. 

How  Much  Do  Ygxjl  Need  to  Know 
About  OS-9? 

You.  might  wonder  how  much  you  really  need  to  know  to  use  OS-9. 
The  answer  varies  with  your  needs,  and  with  the  application 
programs  you  intend  to  use, 

Efowever,  regardless  of  how  you  intend  to  use  your  catnpatra-,  ^kmm 
are  some  OS-9  procedures  you  must  know.  For  instance,  you  must 
know  how  to  load  OS-9,  how  to  prepare  diskettes  to  store  data, 
and  how  to  make  copies  of  data  or  entire  diskettes.  This  part  of 
your  handbook  makes  these  jobs  easy. 

Eegardless  of  how  careful  you  are,  there  are  times  when  things  go 
wrong.  When  this  teppens,  0Sh9  displiEcys  ant  «mr  mmm§^  an  the 
screen.  This  part  of  the  manual  also  helps  you  to  understand 
error  messages  and  what  to  do  about  them. 
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Chapter  2 


How  to  Start  and  Exit  Your 
System 


Starting  your  computer  and  initializing  an  operating  system  is 
inllai  tmii^.  In  a  sense,  the  computer  is  pilli^  teSf  up  ^  its 
bo6i@^3,ps. 

To  run  OS-9,  Level  II,  you  must  have  a  Color  Computer  3  with  at 
least  one  floppy  disk  drive.  Your  OS-9  system  diskette  includes 
modules  to  support  the  following  Color  Computer  hardware: 

•  Up  to  512K  RAM 

•  A  Keyboard 

•  An  Alphanumeric  Video  Display 

•  A  Color  Grai^iics  Display 

•  Floppy  Disk  Drives  (one  or  two) 

•  Jqysticks  (one  or  two) 

•  A  Serial  Printer 

•  An  RS-232C  Communications  Fort 

If  you  connect  a  Multi-Pak  Interface  to  your  computer,  and  use 
the  CONFIG  utility  from  your  BASICOS/CONFIG  diskette  (see 
Chapter  f  J,  OS-9  can  support  the  following  devices 

•  As  mmxj  as  two  external  RS-232  communieattffil  cards 

•  As  many  as  two  modem  paks 

•  As  many  as  two  additional  floppy  disk  drives 

Note:  The  Multi-Pak  Interface  has  four  cartridge  slots. 
A  floppy  disk  controller  must  be  in  Slot  4.  You  can  put 
modem  paks,  or  RS-232  paks  in  Slots  1,  2,  or  3. 


2-1 


Getting  Started  With  OS-9 


Use  the  instructions  in  the  Color  Computer  Disk  System  manual 
to  turn  on  your  computer  system.  After  you  do,  the  video  screen 
displays  a  copyright  message  followed  by  the  letters,  OK.  This  is 
Di^  Extended  Color  BASIC'S  way  of  telling  you  that  it  is  ready 
to  get  to  work.  It  is  waiting  for  your  commands. 

Tq  load  OS-i,  ffiUow  these  steps: 

1.  Insert  the  OS-9  System  Master  diskette  into  Drive  0. 

2.  M  She  OK  prompt,  type: 

DOS  I  ENTER  I 

OS-H  starts.  If  the  DOS  command  returns  a  syntax  error  (SN? 
ERRDR),  be  sure  you  entered  the  command  correctly.  If  DOS 
still  returns  the  error,  check  to  make  sure  you  have  installed 
ytSQT  di^  cartridge  properly. 

3.  After  OS-9  displays  its  startup  messa^,  this  prranpt  appem's: 

f  ^/ mm / d  d  h  h : mm : s  s 
Timef 

4.  Type  the  fear,  month,  date,  hours,  minutes,  and  seconds  in 
the  format  requested;  then  press  I  enter  |.  Fbr  instance,  if  the 
date  and  time  is  September  3, 1986, 1:22  p.m.,  tj^e: 

86/09/03  13:  22  |  ENTER  \ 

Note  that  the  time  is  entered  in  24-hoar  notation  and  that  the 

seconds  (:SS)  are  optional. 

You  can  bypass  this  time  and  date  prompt  by  only  pressing 
1  ENTER  |.  Bsimmm,  if  you  do,  OS-9  cannot  provide  the  cweefc 
date  when  you  create  and  save  data  on  disk.  Also,  it  cannot 
provide  the  correct  date  and  ttsdsi  for  application  programs 
that  require  them. 

After  you  enter  the  date  and  time,  the  OS-9  prompt  appears 
and  OS-9  is  now  in  control  and  ready  to  accept  a  command. 

You  should  always  keep  the  OS-9  System  diskette  in  Drive  0 
(/DO)  v^il©  Kdaning  OS-9  unless  you  have  a  hard  disk  con- 
taining your  system  files.  An  OS-9  System  diskette  is  a 
backup  copy  of  ihe  OS-9  System  Master  diskette.  The  instruc- 
tions for  making  copies  are  in  the  next  chapter. 
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Bebooting  OS-9 

If  you  need  to  reboot  OS-9  after  the  initial  startup,  press  your 
computer's  reset  button  (located  at  the  right  rear  of  the  com- 
puter)^  Pressing  the  reset  button  one  time  causes  the  OS-9  boot 
message  to  reappear.  The  system  then  loads  as  it  did  original]gf. 
Be  sure  the  ^stem  Master  diskette  is  in  Drive  /DO  wfin  ^ai 
reboot. 

Pressing  the  reset  button  twice  returns  the  computer  to  Didt 
BASIC. 

Exiting  OS-9 

In  the  SMtie  m&met  that  fm.  use  OS-9  to  start  operations,  you 
should  use  OS-9  to  exit  or  close  operations.  For  instance,  if  you  are 
in  the  middle  of  a  process,  it  is  unwise  to  suddenly  turn  off  your 
computer.  Doing  so  can  destroy  files  or  garble  didss. 

You  can  usually  tra-minate  an.  Operation  by  pressing  |  break  |  or 
[CTBL I  IT).  In  some  instances,  you  must  let  an  operation  complete 
its  fttlietion  befcre  you  can  regain  control  of  OS-9.  If  you  ftr©  uslhg 
an  application  program,  that  program's  manual  tells  yotl  how  to 
exit  the  program  to  the  OS-9  command  level. 

You  should  always  be  at  the  OS-9  command  level  to  turn  off  your 
computer.  Then  foltow  these  steps: 

1.  Be  sure  the  0S^9  system  prompt  and  cursor  are  displayed. 

Note:  You  can  turn  off  the  OS-9  cursor.  If  you  or  an 
application  prograw  has  done  so,  the  cursor  does  not  dis- 
play at  the  coffittiand  level. 

2.  Take  oUt  any  floppy  diskettes  from  the  disk  drives,  put  them 
back  in  their  protective  envelopes,  and  store  them  in  a  safe 

place. 

3.  Turn  off  all  the  equipment  attached  to  your  computer  such  as 
a  printer  or  disk  drive(s);  then  turn  off  your  TV  or  monitor. 
Last  of  all,  turn  off  your  computer  and  Mijlti-Pak  Interface  (if 
you  haw  Gm%  If  you  plug  your  equipment  into  a  powir  strip, 
you  can  use  tiie  power  strip  switch  to  turn  off  all  equipment  at 
one  time. 
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Upper-  and  Lowercase  Characters 

OS-9  can  display  both  upper-  and  lowercase  letters.  However,  you 
can  tell  it  you  want  to  use  only  uppercase.  To  do  this,  type: 

tmode  upc  |  ENTER  | 

If  you  do  this,  you  cannot  type  lowercase  letters,  and  the  system 
difi|ds^  all  upp^il^ase  lettera.  To  switch  back  to  belh  uppercase 
and  bwercase,  type: 

tmode  -upc  |  HfTEBI 

Even  when  you  are  in  the  upper-Zlowercase  mode,  you  can  switch 
to  typing  all  uppercase  by  pressing  |  ctrl  |  [o].  Everjd:hing  you  type 
is  now  uppercase,  but  the  computer  can  display  both  upper-  and 
lowercase.  Press  |  ctrl  |  [F|  to  switch  back  to  upper-Zlowercase. 

If  you  want  to  type  only  one  uppercase  letter,  hold  down  I  shift  I 
while  you  prei^  msk  letter. 

It  does  not  matter  to  OS-9  t^ether  you  type  in  uppercase  or  low- 
ercase letters,  or  any  combination  of  upper-  and  lowercase  let- 
ters. For  instance,  instead  of  typing  TMDDE  UPC,  you  can  type 
tmode  upc  or  Tmode  UPC. 

OS-9  Error  Messages 

Everyone  makes  a  mistake  now  and  then  when  typing  com- 
mands. If  you  type  something  the  operating  system  doesn't  rec- 
ognize, or  if  you  ask  it  to  do  something  it  cannot  do,  it  displays  an 
error  message.  This  message  is  a  number  that  refers  to  the  type 
of  problem  that  OS-9  has  encountered.  Pbr  instance,  if  you  type 
XX  XX  I EWHB I  (whichi  is  nonsmse  to  OS-9),  the  system  disidays: 

ERROR  #216 

If  you  don't  know  the  meaning  of  the  system  error  number  you 
have  two  options:  (1)  you  can  look  up  the  reference  in  OS-9 
Commands  tinder  Appendix  A,  "Error  Codes"  or,  (2)  ytm  can 
type: 

ERROR   21  e  I  ENTER  | 

Either  method  shows  you  that  Error  #216  means  "Path  Name 
Not  Found."  OS-9  thoi^t  ym  wanted  it  to  esecute  a  command 
but  it  could  not  find  one  named  xxxx. 


2-4 


How  to  Start  and  Exit  Your  System  1 2 


Other  OS-9  error  messages  tell  you  if  you  have  used  all  of  a  disk's 
storage  space,  if  the  ccttttpi'ta''iS  memory  is  full,  if  yoii  try  to  cre- 
ate two  files  with  the  smne  name,  and  so  on. 
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Chapter  3 


What  You  Need  to  Know 
To  Use  Floppy  Drives 


Floppy  diskettes  require  careful  handling.  You  might  already  be 
familiar  with  how  to  take  care  of  diskettes  from  reading  your 
Color  Computer  Disk  System  manual.  If  not,  or  as  a  reminder, 
review  the  followiiig  points: 

•  iitlw&fs  make  copies  of  important  diskettes.  The  price  of  a 

diskette  is  small  compared  to  the  time  it  can  take  to 

replace  destroyed  data. 

•  Copy  data  you  are  working  with  regularly.  If  you  experi- 
ence a  power  failure  while  using  your  computer,  the  data 
on  any  diskettes  you  have  in  a  drive  can  be  destroyed. 
Other  accidents  can  happen  as  Wsd:!. 

•  Alwag^s  keep  the  protective  paper  or  cardboard  envielppe  on 
your  diskette  when  it  is  not  in  use. 

•  Y)ur  drive  accesses  a  diskette  through  the  oblong  slot  in 
the  diskette's  jacket.  Never  touch  the  diskette  through 
this  hole.  The  oil  from  even  the  cleanest  hand  can  destroy 
data,  making  the  diskette  useless. 

•  Do  not  bend  diskettes. 

•  Store  diskettes  away  from  excessive  heat,  dust,  and  any 
magnetic  source.  Even  coniponents  in  didk  drives,  video 
displays,  TVs,  and  electric  motors  can  garble  the  data  on 

diskettes. 

•  If  you  must  write  on  a  diskette  label  after  placing  it  on 
the  diskette,  use  only  a  soft  felt  pen. 

•  Do  not  switch  your  computer,  disk  drive(s),  or  Multi-Pak 
interface  on  or  off  while  you  have  a  diskette  in  a  disk 
drive, 
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Write  Protection  for  Diskettes 


Most  diskettes  have  a  square  notch  cut  from  one  comer.  This  is  a 
write  protect  notch.  K  you  plaice  a  special  adhesive  tab  (supplied 
with  diskettes)  over  both  sides  of  tJiis  notch,  your  computer  can  no 
longer  write  (store)  data  on  it.  This  feature  protects  diskettes  from 
inadvertent  destruction  of  data. 

Removing  the  tab  again  lets  you  write  data  onto  the  diskette. 

Disk  Drive  Names 

OS-9  has  its  own  method  of  refering  to  your  disk  drives.  What 
your  Cobr  Computer  Disk  System  manual  calls  Drive  0,  OS-9  calls 
Drive  /DO.  This  is  your  first  drive  if  you  have  more  than  one 
floppy  disk  drive  connected  to  your  syst^.  Subsegumt  drives  are 

named  /Dl,  /D2,  and  so  on. 

If  you  have  a  hard  disk  attached  to  your  system,  OS-9  refers  to  it 
as  DriiMs  fflCO,  A  MiOBi  hard  disk  drive  is  named  /HI. 
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Making  Copies  of  Diskettes 

Before  you  can  store  information  on  a  diskette,  you  must  format  it. 
Formatting  is  the  process  of  magnetically  arranging  a  disk's  sur- 
face so  that  iy&-d  caai  stdre  and  locgfte  ffifottrtatittft.  The  following 
steps  tell  you  how  to  format  a  diskette.  Format  at  least  two 
diskettes  at  this  time  to  use  in  making  backups  (copies)  of  your 
two  OS-9  system  diskettes.  If  you  have  other  important  diskettes 
to  backup,  format  as  many  di^ttes  as  you  require. 

BniilaitMng  Mth  Otie  Disk  Drive 

1.  If  you  have  not  already  done  so,  place  a  write-protect  tab  on 
your  System  Master  diskette.  Then,  turn  on  and  boot  your 
computer  as  described  in  Chapter  2. 

2.  With  the  OS-9  System  Master  diskette  in  your  drive,  type: 

load   format  |  ENTER  |. 

3.  Select  a  diskette  that  does  not  contain  data  or  that  contains 
data  you  do  not  want  to  keep.  Make  sure  it  does  not  have  a  foil 
tab  covering  the  write-protect  notch.  Put  it  in  your  disk  drive 
(Drive  /DO)  in  place  of  your  OS-9  System  Master  diskette  and 
type: 

format  /d0  |  ENTER  I 

The  following  prompt  appears: 

COLOR   COMPUTER  FORMATTER 
Formatting  drive  /d0 
y  tyes)  or  n  (no) 
Ready? 

4.  Press  [Y]  to  begin  formatting.  OS-9  asks  you  for  a  Disk  Name:. 
Type  any  name,  using  a  maximum  of  32  characters.  For 
sample,  you  can  type  s  |  emter  |  to  name  the  tokette  "s." 

Next  OS-9  verifies  that  the  diskette  is  formatted  properly.  The 
screen  shows  each  track  number  in  hexadecimal  notation  dur- 
ing verification.  A  track  is  a  concentric  rixig  around  the 
diskette  on  which  information  is  stored. 
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5.  When  formatting  is  complete,  OS-9  shows  you  the  Number  of 
good  sectors.  This  number  depends  on  the  type  of  disk  drive 
you  are  using.  For  a  35  track,  single-sided  drive,  the  number 
should  be  $000276  (hexadecimal  276  sectors).  The  OS-9  prompt 
and  ciu-sor  reappear.  Remove  the  newly  formfittsfi  (fi^tte  from 
the  drive,  and  store  it  in  a  safe  place  until  you  are  ready  to  use 
it. 

Ebrmat  as  many  diskettes  as  you  need  by  following  Steps  3 
through  5. 

Formatting  With  Two  Disk  Drives 

1.  If  your  computer  is  off,  turn  it  on,  and  boot  OS-9  as  outUned  in 
Chapter  2. 

2.  At  the  sptaai:  p§»pt  CaiiiitJ,  tfpe  f  stmat  /di  i  enter  i.  The 
screen  shows; 

CDLDR  COMPUTER  FORMATTER 
Formatting  drive  /d1 
y  Cyes)  or  n  (no) 

Ready? 

3.  Insert  a  blank  disk,  or  one  which  does  not  contain  data  you 
Wafit  to  keep,  into  Drive  /Dl,  and  close  the  latch.  Be  sure  the 
diskette  does  not  have  a  foil  tab  covering  the  write-protect 

notch.  Press  (Y). 

4.  OS-9  formats  the  diskette;  then  asks  you  for  a  Disk  Name:. 
Type  any  name,  using  a  maximum  of  32  characters.  Fbr 
example,  you  can  type  s  |  enter  |  to  name  the  diskette  "s." 

Next  OS-9  verifies  that  the  diskette  is  formatted  properly.  The 
screen  shows  each  track  number  in  hexadecimal  notation  dur- 
ing verification.  A  track  is  a  concentric  ring  around  the 
diskette  on  which  information  is  stored. 

5.  When  formatting  finishes,  OS-9  shows  you  the  Number  of 
good  sectors.  This  number  depends  on  the  type  of  disk  drive 
you  are  using.  For  a  35-track,  single-sided  drive,  the  number 
should  be  $000276  (hexadecimal  276  sectca-s).  The  OS-9  prompt 
and  cursor  reappear.  Remove  the  newly  formatted  diskette  from 
the  drive,  and  store  it  in  a  safe  place  until  you  are  ready  to  use 
it. 
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Format  as  majiy  disfeettes  as  you  need  by  following  the  same 
procedure. 

Using  the  Backup  Cominaiid 

BACKUP  is  one  OS-9  command  feat  you  can  ex|«isfc  use  fee- 
quently.  It  is  the  command  yraa  we  to  mate  etpfes  of  your 
diskettes.  We  sttongfy  recoinilteitd  ihat  yon  ntm  nse  'Qa.e  fol- 
lowing instructions  to  make  copies  of  your  OS-9  system 
diskettes.  You  can  only  copy  diskettes  that  are  created  in  the 
same  type  of  disk  drive  you  are  using.  "Sjur  OS-9  system  diskettes 
are  35  track,  single  sided. 

BACKUP  uses  two  trams  you  need  to  understand.  They  are  source 
and  destiiration.  A  source  diskette  is  the  diskette  that  contains  the 
program,  file  or  data  that  you  want  to  backup.  The  destination 
diskette  is  the  blank  formatted  diskette  you  prepared  to  receive 
the  c(^ied  data. 

Note:  Some  application  programs  you  buy  do  not  let  you 
make  copies  of  their  diskettes.  Check  the  program  manual 
for  information  on  protecting  the  data  on  these  diskettes. 

Making  Copies  With  One  Disk  Drive 

1.  If  your  computer  is  off,  turn  it  on,  and  boot  OS-9  as  outlined 

at  the  beginning  of  Chapter  2. 

2.  At  the  system  prompt  (DSS : ),  type: 

backup   /d0   #32K  |  ENTER  | 

This  tells  OS-9  to  make  a  backup  of  the  diskette  in  Drive  /DO. 
The  screen  displays  the  following  prompt: 

Ready  to  backup  from  /d0  to  /d0 

3.  Leave  the  gystsm  Master  dinette  in  Drive  iDO  to  make  a 
backup  of  it.  Tb  back  up  one  of  your  other  d&kettes,  for  exam- 
ple the  BASIC09/CONFIG  diskette,  remove  the  System  Master 
diskette  and  replace  it  w^ith  the  diskette  you  want  to  copy. 

4.  Press  [Y]  when  you  are  ready  to  continue.  The  screen  displays: 

Ready  Destination,    hit   a  key: 
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5.  Replace  the  source  diskette  with  the  destination  diskette.  Then, 
press  the  space  bar  to  continue  BACKUP. 

When  you  bacl:  up  one  diskette  to  another,  any  data  previ- 
ously existing  on  the  destination  diskette  is  overwritten 
(destroyed).  OS-9  gives  you  a  chance  to  make  sure  you  have 
Inaertid  the  prtper  destination  diskette  by  diaplaying  the 
xnesffage: 

DISK  NAME 

is  being  scratched 
Ok  ?: 

"Scratched"  means  that  OS-9  is  going  to  replace  any  data  on 
the  diskette  with  new  data  from  the  source  diskette.  BACKUP 
also  gives  the  destination  diskette  the  same  name  as  the  souroe 
diskette — the  destination  becomes  a  duplicate  of  the  source. 

6.  Press  [¥}  to  keep  going.  The  screen  asks  you  to: 

Ready  Source,    hit    a  key: 

7.  Remove  the  formatted  diskette  from  Drive  /DO,  and  replace  it 
with  the  source  diskette  that  contains  the  data  you  want  to 
copy.  Press  the  space  bar. 

In  a  moinettt,  a  prompt  asks  you  to: 

Ready  Destination,  hit  a  key; 

8.  Remove  the  source  diskette  and  replace  it  with  the  destination 
diskette.  Press  the  space  bar. 

9.  Continue  switching  diskettes  as  the  screen  instructs  you  until 
you  see: 

Sectors       copied :  $0276 

Verify   pa  5  S 

Followed  in  a  xmmmsak  by; 

Sectors  verified!  $0276 
aS9: 
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The  diskette  now  in  your  drive,  the  destination  diskette,  is  a 
duplicate  of  the  source  diskette.  If  you  copied  the  System  Master 
or  the  BASIC09/CONFIG  diskette,  store  it  in  a  safe  place,  and 
use  the  copy  as  your  working  diskette.  Reserve  the  original 
diskette  tor  making  future  backups. 

Note:  For  computers  with  512K  of  memory,  OS-9  can 
backup  a  diskette  &ster  if  you  replace  #32K  in  Step  2  with 
#56K. 

Makiiig  Copies  With  Two  Disk  Drives 

1.  If  your  computer  is  off,  turn  it  on,  and  boot  OS-9  as  outlined 
at  the  beginning  of  Chapter  2. 

2.  At  the  system  prompt  (DS9 :),  type: 

backup   /d0    /d1    #32K  |  ENTER  | 

This  tells  OS-9  to  make  a  backup  of  the  diskette  in  Drive  /DO. 

The  screen  displays  the  following  prompt: 

Ready  to  backup  from  /d0  to  /d1 
?: 

3.  Leave  Ifhe  %st€sm  Master  diskette  in  Drive  /DO  to  make  a 
backup  of  it.  To  back  up  one  of  your  other  diskettes,  for  exam- 
ple the  BASIC09/CONFIG  diskette,  remove  the  System  Master 
diskette  and  replace  it  with  the  diskette  you  want  to  cokt. 

4.  Press  (T]  when  you  are  reac^y  to  continue. 

When  you  back  up  one  diskette  to  another,  the  process  over- 
writes or  destroys  any  data  previously  existing  on  the  destina- 
tion  di^e^.  0^9  ^ves  yaa  a  dbanee  to  mim  ym  We 
inserted  the  proper  destination  diskette  by  displaying  the 

message: 

DISK  NAME 

is  being  scratched 

□  k    ?  : 

"Scratched"  means  that  OS-9  replaces  any  data  on  the  des- 
tination diskette  with  new  data  from  the  source  di^tte. 
As  well,  BACKUP  gives  the  destination  diskette  the  same 
name  as  the  source  diskette — the  destination  becomes  an 
exact  duplicate  of  the  source. 
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6.  Press  (T|  to  keep  going. 

Copying  continues.  When  the  procedure  ends,  you  see: 

Sectors       copied:  $027G 
Verify  pa a a 

Ibllowed  in  a  moim&%  %i 

Sectors  veFified:  10276 
aS9: 

The  diskette  in  Drive  /Dl  is  now  a  duplicate  of  the  source 
diskette.  If  you  copied  the  System  Master  or  the  BASIC09/ 
CONFIG  diskette,  store  it  in  a  safe  place,  and  use  the  copy  as 
your  working  diskette.  Reserve  the  original  diskette  for  making 
future  backups. 

Note:  Rjr  computers  with  S12K  of  memory,  OS-9  can  backup 
a  diskette  faster  if  you  replace  #32K  in  Step  2  with  #56K. 
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Organization,  Commands, 
and  Keys 


Chapter  4 


Files  and  Directories 


Before  you  can  use  OS-9  extensively,  you  need  to  know  how  the 
system  organizes  and  stores  datsi  on  digk.  The  infonmtipn  in  this 
section  is  true  for  both  floppy  diskettes  and  hard  M&s.  Riwe^er, 
because  of  the  greater  storage  capacity  of  a  hard  disk,  it  is  of 
particular  importance  to  hard  disk  users. 

About  Files 

Consider  the  information  stored  on  disks  to  be  of  two  basic  types^ 
programs  and  data.  A  program  is  code  that  causes  your  com- 
puter to  execute  a  task.  Data  is  information  that  a  program  uses 
or  that  a  program  creates. 

All  the  information  that  OS-9  stores  on  disks,  whether  program  or 
data,  is  stored  in  units  called  files.  Whenever  a  program  creates 
a  fife,  0§Mi  d^ii^  a  poPtteft  iof  your  disk  to  sto*e  it.  B  keeps  the 
location  of  the  file  in  a  special  list  (called  a  directory),  also  located 
on  the  disk,  so  that  it  knows  where  to  find  your  program  or  data 
the  next  time  you  want  it. 

About  Directories 

A  directory  is  a  storage  space  for  filenames,  other  directory 
names,  or  both. 

After  you  format  a  disk,  it  contains  one  directory  called  the 
ROOT  directory.  However,  a  disk  can  have  many  directories.  For 
instance,  besides  the  ROOT  directory,  your  System  Master 
diskette  contains  thi  CMDS  and  SYS  directories.  The  ROOT  and 
CMDS  directories  are  especially  important  to  you. 

When  you  boot  OS-9,  you  automatically  begin  operation  from 
these  two  directories.  The  ROOT  directory  becomes  your  current 
data  directory  and  thB  CMDS  directory  becomes  your  current 

execution  directory. 

Whenever  you  ask  OS-9  to  store  a  file  on  a  diskette,  it  automati- 
cally stores  it  in  the  current  data  directory  (the  ROOT  direc- 
tory), unless  you  tell  it  otherwise.  If  you  ask  OS-9  to  execute  a 
command  or  program,  it  automatically  looks  for  that  command  or 
program  in  the  execution  directory  (the  CMDS  directory),  unless 
you  tell  it  otherwise. 
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Every  OS-9  directory  can  also  contain  other  directories,  called 
suhdiremrtm.  W&t  mstattce,  WS,  aftd  (3MDS  are  establldied  as 
subdirectories  of  the  ROOT  directory.  Put  in  chart  form,  your 
ROOT  directory  with  its  subdirectories  looks  like  this: 

  ROOT  DIRECTORY   


V 

CMOS 


V 
SYS 


Figure  4.1 


But  there  are  also  files  in  the  ROOT  directory,  OS9Boot  and 
Startup  are  two.  The  full  ROOT  directory  might  look  like  this: 

  ROOT  DIRECTOEY   

i 

OSBBoot 
Startup 


CMOS 


SYS 


Figure  4.2 


Iftdt  &m.  &esM  mdSsm  subdirectory  of  the  ROOT  directory  if  you 
want.  Fbr  instance,  if  you  created  a  directory  named  E^MIIY,  the 
chart  of  the  ROOT  directory  looks  like  this: 

  ROOT  DIRECTORY  — 


OSQBoot 
Startup 


CMDS 


FAMILY 


SYS 


Figure  4.3 
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After  you  create  the  FAMILY  directory,  you  can  also  create  other 

directories  in  it.  Suppose  you  create  two  subdirectories  named 
PLEASURE  and  WORK.  The  chart  organization  is  as  follows: 

-    ROOT  DIRECTORY   

V 

OS9Boot 
Startup 


CMDS 


f 


E\MILY 


PLEASURE 


1/ 
WORK 


SYS 


Figure  4.4 


The  directories  you  create  also  ma  hold  files.  Jf  ym  asmiei.  i^ee 
files  each  in  the  PLEASURE  and  WORK  directories,  tbe  chart 

might  look  like  this: 

—    ROOT  DIRECTORY   


V 

OS9Boot 
Startup 


CMDS 


f 


V 

FAMILY 


PLEASURE 


mom 
dad 
joe 


1. 

WORK 

mom 

dad 
joe 


V 

SYS 


Figure  4.5 

You  can  condnue  to  create  files  and  subdirectories  in  any  or  all  of 
your  disk's  directories  imtil  you  fill  the  di^'s  storage  space. 
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Multiple  Dibpectories 

There  is  nothing  wrong  with  storing  all  your  files  in  the  ROOT 
directory.  Doing  so  makes  it  easy  to  access  them  because  they  are 
always  in  your  data  directory. 

However,  creating  multiple  directories  makes  it  easy  to  keep  your 
data  organized  when  you  have  many  files,  or  if  more  than  one 
person  is  using  the  same  disk.  Such  a  multiple-diirectory  organi- 
zation is  especially  helpful  when  using  hard  di^s,  which  can 

store  hundreds  of  individual  files. 

Also,  when  you  have  multiple  directories,  you  can  store  files  hav- 
ing the  same  name  in  different  directories  without  conflict,  such 
as  in  the  PLEASURE  and  the  WORK  directories  of  Figure  4.5. 

About  File  and  Directory  Names 

The  file  and  directory  names  shown  so  far  consist  only  of  letters 
of  the  alphabet,  but  you  can  use  other  characters  and  symbols  in 
a  file  or  directory  n£ime  as  long  as  each  name  begins  with  a  let- 
ter. The  fidloisSftg  is  a  ceraiflete  list  of  acceptable  characteFs: 

•  Upp^case  letters:  (A-E) 

•  Lowercase  letters:  (a-z) 

•  Decimal  cttpi:  (0-9) 

•  The  trndisrscore  character  (  )  and  the  period  (.) 

can  include  as  many  as  29  characters  in  a  file  or  directory 
name. 

Examples  of  Filenames 

The  following  are  samples  of  filenames  that  OS-9  can  recognize: 

mydata  samfile 
mydatal  Dollar_gifts 
records.srt  help.file 


XXX.XX 

progl.bas 
prog2.bas 


«le#l.txt 

program.sourcecode 
program,  opcode 
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Examples  of  invalid  filenames  are: 

his*hers   because  *  is  not  a  valid  character  for 

names 

.DATA  ,  because  the  name  does  not  begin  with 

a  letter 

COST + INT  ,  because  +  is  not  a  valid  character  for 

names 

lOO-dollar-gifls  . .  .because  names  cannot  begin  with  a 
digit 

About  Pathlists 

Because  you  can  organize  OS-9  disks  into  multiple  levels,  you 
need  a  way  to  tell  the  system  where  to  find  directories  and  files. 

The  directions  you  give  are  called  pathlists. 

A  pathlist  is  exactly  what  its  name  implies — a  path  (or  route)  to 
the  device,  directory,  or  file  you  want  to  access.  For  instance,  if 
you  are  in  the  ROOT  directory  (see  Figure  4.5)  and  want  to  look 
at  the  contents  of  a  file  in  the  WORK  directory,  you  must  tell 
OS-9  how  to  get  there.  The  pathlist  from  the  ROOT  directory  to 
the  Dad  file  is  family/work /dad.  OS-9  expects  you  to  separate 
the  jmctiiW  of  pathlists  with  slashes.  To  look  at  the  contents  of 
Dad,  you  type: 

list  f ami ly/wor k/dad  lESTBtil 

Because  you  are  accessing  a  file  on  the  current  disk,  you  do  not 
need  to  specify  a  drive  name.  Because  every  disk  contains  a 
ROOT  directory,  and  all  other  directories  and  files  branch  from  it, 
ROOT  is  always  implied  in  a  pathlist.  If  Fig;ure  4,5  represented 
tlie  dinette  in  Drive  /Dl,  tha  pa'^maioe  to  the  Dad  file  wmM  be 

/dl/fami ly/wor k/dad. 

Depending  on  the  location  of  the  directory  or  file  you  want  to 
access,  a  full  pathlist  need  not  contain  any  more  than  the  name 
of  a  drive,  the  name  of  a  directory,  or  the  name  of  a  file.  For 
instance,  the  complete  pathlist  from  the  ROOT  directory  of  Fig- 
ure 4.5  to  the  Startup  file  is  startup.  Tb  locdc  at  the  contents  of 
Startup,  tj^: 

list  startup  rENTERl 
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Anonymous  Directory  Names 

To  save  time,  or  if  you  do  not  know  a  full  pathlist,  you  can  refer 
to  the  current  directory,  or  to  a  higher-level  directory,  using  an 
anonymous  name,  or  name  substitute,  as  follows: 

•  One  period  (.)  refers  to  the  current  directory 

•  Two  periods  (..)  refer  to  the  parent  of  the  current  direc- 
tory (the  next  highest-level  directory). 

•  Three  periods  (...)  refer  to  the  directory  two  levels  up,  and 
so  on. 

l&u  can  use  an  anonymous  directory  name  in  place  of  a  pathlist 
ot  as  the  first  name  in  a  pathlist.  Some  examples  are: 

d  i  r  . .  I  ENTER  |  lists  names  in  the  current  data  direc- 
tory's parent  directory. 

del  .  ./temp  | ENTER | deletes  the  file  called  Temp  from  the 
current  data  directory's  parent 
directory. 

Anonymous  names  can  refer  to  either  execution  or  data  directo- 
ries, A^mdiKtf  on  the  context  in  which  you  use  them. 

About  Device  Nmmm 

In  the  same  manner  that  OS-9  has  names  for  its  commands,  it 
also  has  names  for  its  devices.  These  names  are  abbreviations  of 
actual  device  names.  Pbr  instance,  instead  of  typing  Disk  Drive  0 
to  refer  to  your  first  disk  drive*  you  only  need  to  type  /D0,  To 
refer  to  your  printer,  type  /P,  OS-9  wioilBWS  are  HKmed  fl^ 
through  /W7. 

All  of  OS-9's  device  names  are  preceded  by  a  slash — this  is  how 
OS-9  can  tell  you  are  referring  to  a  device  rather  than  a  direc- 
tcsey  or  file.  When  you  purchase  your  System  Master  diskette,  OS- 
9  is  configured  to  recognize  two  disk  drives,  a  printer,  and  QXm 
terminal  port.  Rjr  infbtniatian  oii  how  to  ccaifigure  your  systett  ^ 
recognize  other  devices,  see  Chapter  7. 


4-6 


Chapter  5 


Commands  and  Keys 


You  already  put  OS-9  to  work  with  commands  such  as  FORMAT 
and  BACKUP.  In  these  We&es  the  manual  told  you  exactly  what  to 
do  to  accomplish  a  yeey  Specific  task.  If  you  want  to  strike  out  on 
your  own,  you  stoouli  koow  some  adiliional  baekgrotmd 
information. 

Typing  Commands 

As  explained  earlier,  some  OS-9  files  are  programs,  "fcu  tell  OS-9 
to  mmiie  Ihem  programs  by  typing  the  pr^taxn  (file)  name  and 
pressing  |  enter  |.  You  are  then  issuing  a  command  to  OS-9.  That's 
all  a  command  is,  the  name  of  a  program  for  the  system  to  exe- 
cute. The  following  are  some  rules  about  commands: 

•  You  can  enter  a  command  whenever  the  screen  displ^s 
the  system  prompt  (dsb  : ). 

•  A  command  consists  of  one  word,  the  command  name.  A 
emimand  line  consists  of  one  or  more  command  names 

and  their  associated  parameters  and  modifiers.  Parame- 
ters and  modifiers  are  special  information  you  include 
with  a  command  that  provide  necessary  data  for  the  com- 
mand to  operate,  or  that  affect  the  command's  operation. 

•  A  command  line  can  hay©  a  maximum  of  198  characters 
including  any  combination  of  upper-  or  lowercase  leMers. 
To  execute  a  command,  press  I  enter  |.  Pbr  example,  to  clear 

the  screen,  type: 

display   0c  |  ENTER  | 

Editing  Commands 

OS-9  is  very  particular  about  the  commands  you  type.  If  you 
make  any  mistake,  OS-9  either  does  not  imderstand  (and  tells  you 
so  with  an  error  message)  or  does  the  wrong  thing. 

If  you  see  that  you  made  a  mistake  before  you  press  |  enter  |,  you 
have  two  choices:  (1)  use  or  |  ctrl  |  [W\  to  move  the  cursor  to  the 
mistake,  and  retype  that  portion  of  the  line,  or  (2)  press  |  ctrl  |  (T) 
or  I  SHIFT  I  @  to  erase  the  line  ym.  are  typing,  and  start  over. 
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Command  Parameters 


can  follow  a  command  name  with  one  ac  more  parameters 
that  giw  OS»S  mare  ^pacifie  tosteiffitiaiis.  Ear  ecamsfle,  in 
command  line: 


list  filel  I  ENTER  I 

LIST  is  the  name  of  the  command  that  displays  the  contents  of  a 
text  file.  Fikl,  the  specified  parameter,  is  the  name  of  the  file 
that  you  want  displayed. 

Note:  In  a  command  line,  always  use  spaces  to  separate 
parameters  from  their  cQBiBaajad,  and  from  each  other. 
Parameters  cannot  cotttain  spaces.  OMpter  6  disetiases 
parameters  &r  each  OS-9  command. 

Some  commands  have  more  than  one  parameter.  For  instance, 
COPY  requires  two  parameters:  the  name  of  the  file  being  cop- 
iedi,  and  the  name  of  the  new  file  you  want  COPY  to  create.  If  you 
want  to  copy  a  file  called  Startup,  and  call  the  copy  Newstartup, 
your  comm£ind  line  reads: 

  COPY,  the  command 

name. 

  The  name  of  the  file 

to  copy 

  The  name  of  the  copy 


I —  Yaa  press  I  enter  |  to 
cause  the  command 
line  to  execute. 


copy  startup  newstartup  riNTERl 


Using  Options 

Command  lines  can  also  eaisMxi  another  type  of  paranaslter,  called 
an  option.  An  option  changes  the  way  a  command  performs.  For 
instance,  the  command  DIR,  without  parameters,  shows  the  name 
of  all  files  in  the  current  data  directory. 
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However,  if  you  add  the  E  option  as  a  parameter  to  the  com- 
mand, like  this: 

d  ir   e  I  ENTER  | 

the  output  includes  not  only  the  names  of  the  files,  but  also  com- 
plete statistics  about  each  file — ^the  date  and  time  created,  size, 

security  codes,  and  so  forth. 

To  display  complete  information  about  each  file  in  SYS,  type: 
dir   sys   e  |  ENTER  | 

Using  Commands 

As  described  in  Part  1,  QS-9  acts  in  mach  'the  same  mating  as 

an  office  manager.  It  looks  after  the  operation  of  your  computer 
and  equipment.  Because  OS-9  is  only  a  manager,  it  expects  you 
to  make  the  necessary  decisions. 

For  example,  suppose  you  have  an  important  file  named  IfotstufF 
that  you  want  to  copy.  Before  giving  it  to  your  office  manager 
(C^d),  ysa  mu@l  make  executive  decisiocts,  smh.  as: 

•  Do  you  TOtnt  the  caps  on  disk,  faper,  or  the  compute: 
screen? 

•  If  you  want  lie  c<^  on  disk,  which  disk? 

•  If  you  want  the  copy  on  the  same  disk,  what  name  do  you 
want  to  give  the  second  copy  so  OS-9  is  not  confused? 

•  If  you  want  the  copy  on  the  computer  screen,  do  you  want 
the  display  to  pause  when  it  fills  the  screen? 

"Sou  make  the  decisions,  OS-9  manages  the  job.  For  instance,  if 
your  decision  is  to  copy  Hotstuff  from  one  diskette  to  another, 
you  might  type  the  following  command  line: 

copy  /dB/hotstuff  /d1  /hot  copy  |  ENTERI 
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This  is  how  OS-9  sees  your  command: 

  The  name  of  the 

command 


The  disk  drive 
containing  the  file  to  be 
copied 

The  name  of  the  file  to 
copy 

The  disk  drive  that  is  to 
receive  the  new  file 


The  name  of  the  copy 


copy  /d0/hot stuff  /d1/hotoopy 


This  command  line  tells  OS-9  to  copy  a  file  named  Hotstuff  from 
your  floppy  disk  Drive  /DO  to  a  second  floppy  Drive  /Dl.  The  file 
copy  is  given  the  mew  name,  Hotcopy. 

You  only  need  to  know  the  name  of  the  file  you  want  to  copy,  on 
which  disk  it  is  located,  and  the  disk  on  which  you  want  the  new 
copy.  OS-9  manages  the  operation  for  you. 


Aceessix^  Commands 

OS-9  has  two  ways  to  access  commands.  Some  commands  reside 
on  a  disk.  When  you  type  the  command  name  and  press  |  enter  |, 
OS-9  must  look  on  the  disk,  load  the  program  into  the  comput- 
er's memory,  and  then  execute  it. 

Other  commands  are  loaded  into  your  computer's  memory  at 
startup,  or  you  can  load  them  into  memory  later.  When  you  call 
a  command  that  is  in  memory,  it  is  executed  immediately.  There 
is  no  delay  while  OS-9  finds  it  on  disk. 
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Commands  from  Disk 

When  you  give  OS-9  a  command  that  it  cannot  find  in  memory,  it 
looks  for  the  command  in  the  current  execution  directory.  If  it 
caimot  find  it  there,  it  checks  the  current  data  directory.  If  it  still 
cannot  find  it,  the  system  issues  Error  IVfessage  #216,  Path,  Name 
Not  Fbund.  If  the  command  you  want  executed  rs  in  a  directory 
other  than  the  current  directory,  you  must  tell  OS-9  where  to  find 
it.  Remember,  when  initialized,  OS-9  sets  the  CMDS  directory  of 
the  system  disk  to  be  the  execution  directory. 

RjT  instance,  suppose  you  booted  your  system  using  a  diskette 
configured  like  the  example  we  used  in  Chapter  4: 


ROOT  niRECTORY 


V 

CMDS 


V 

OS9Boot 
Startup 


V 


V 

SYS 


■FAMILY  — , 


PLEASURE 


V 

WORK 


mom 


mom 


dad 
joe 


dad 
joe 
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When  the  system  starts,  the  ROOT  directory  is  the  data  direc- 
tcBpy,  aiai  the  CMDS  directory  is  the  execution  directory.  Now, 
suppose  you  had  a  program  named  Expenses  in  the  family 
directory: 

  ROOT  DIRECTORY   


CMDS 


V 

OS9Boot 
Startup 


-FAMILY 


SYS 


\^    expenses  ^ 


PLEASURE 


WORK 


i 


mom 
dad 
joe 


mom 

dad 
joe 


(Remember  that  a  program  and  a  command  are  really  the  same 
thing.) 

You  can  now  access  (use)  the  expenses  program  in  two  ways.  One 
way  is  to  specify  a  pathlist  from  the  ROOT  directory  to  execute 
Expenses,  such  as: 


/d0/f  ami  ly/expenses  [ ENTER  | 

Another  way  is  to  change  the  execution  directory. 


Changing  the  Execution  Directory 

To  change  the  execution  directory  to  the  FAMILY  directory,  type: 


chx   /d0/f  ami  ly  |  ENTER  | 

Or  specify  a  pathlist  relative  to  the  current  execution  directory, 
such  as: 


chx  .  ,  /  family  I fiNTtlil 

To  j^eeigmte  thi.  BxpiaaBft  program,  you  now  only  need  to  type 
expen  sea  I  EMTgft  |. 
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'Smmmct  after  ymi  eJiai^  the  execution  direcitory,  to  use  a  cqm- 
mm£  in  ttoe  OCMilANDS  directory,  you  tm^  tell  0&.9  ttee  to 
find  it.  Bbr  example^  to  format  a  new  diskette  in  Drive  /Dl,  type: 

/d0/cmds/f ormat  /d1 

Changing  the  Data  Directory 

Suppose  that  the  Expenses  program  keeps  track  of  work  and 
pleasure  expenses  for  Mom,  Dad,  and  Joe.  Unless  you  tell  OS-9 
otherwise,  it  looks  for  data  files  in  the  current  data  directory,  the 
ROOT  directory.  To  tell  OS-9  to  look  for  data  files  in  the  PLEA- 
SURE directory,  type: 

chd  f amily/pleaaure  [ENTERl 

The  slash  between  FAMILY  and  PLEASURE  tells  the  system  that 
PLEASURE  is  a  branch  of  FAMILY.  Subordinate  directories  and 
files  are  always  se|«arated  &««a  their  parsffiEb  in  #dte  m^. 

How,  mTmx  Expenses  needs  data,  it  knows  to  look  in  the  PLEA- 
SURE directory. 

Changing  System  Diskettes 

Although  it  is  preferable  to  leave  the  system  diskette  in  {d^ace 
while  the  system  is  running,  partieulafly  with  mul'^ttSif 
tems,  there  might  be  times  when  you  need  to  use  anothei' 
diskette.  Only  remove  the  current  diskette  when  the  screen  dis- 
plays the  OS-9  prompt,  followed  by  the  cursor.  If  you  do  remove 
the  system  diskette  and  begin  to  use  another  one,  use  the  CHD 
and  CHX  commands  to  tell  OS-9  where  you  want  to  be  located  on 
the  new  diskette.  (For  directions,  see  Chapters  2  and  6.)  Those 
commands  set  both  directory  pointers,  data  and  esrecution,  for  the 
new  diskette. 

While  using  a  program  or  command,  do  not  remove  a  diskette  and 
insert  another  unless  the  program  or  command  asks  you  to.  You 
can  lose  data,  or  entire  files,  if  you  do. 
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Video  Display  and  Keyboard  Functions 

OS-9  has  many  features  that  expand  the  capability  of  the  Color 
Computer's  video  display  and  keyboard. 

•  The  video  display  has  uppaf-flefWiercase,  screen  pause, 
graphics  functions,  and  80  column  displstys  if  you  have  a 
monitor  connected. 

•  The  I  ALT  I  key  provides  an  alternate  key  function.  Holding 
down  I  ALT  I  while  pressing  another  key  sets  the  high  order 
bit  of  ike  character  pressed.  That  is,  it  adds  128  to  the 
normal  ASCfl  value  produced  by  that  key.  Holding  down 
I  ALT  I  while  pressing  any  other  key  produces  a  graphics 
character  on  the  standard  VDG  screen.  If  you  are  using 
windows,  |  alt  |  lets  you  produce  international  characters. 
(See  OS-9  Windowing  System  Owner's  Manual  for  more 
information). 

•  The  keyboard  has  an  auto-repeat  function.  Holding  down 
a  key  causes  the  character  to  repeat  until  you  release  the 
key.  This  function  operates  properly  only  when  the  disk 
drives  are  not  in  use  bf  a  pRagiam. 

•  Ym  can  d^  with  the  video  display  afii  fe^boaM  fopihef 
as  though  they  are  a  file.  You  can  receive  input  from  the 
keyboard  and  send  output  to  the  video  screen  using  the 
device  name  /TEBM. 

Special  Keys 

The  following  keys  and  key  sequences  have  special  significance 


to  OS-9. 


Produces  graphic  charaCtafS  Oil  a  stan- 
dard VDG  screen  or  international 
characters  with  windows.  Press  I  alt  | 
char  (where  char  is  a  keyboard  charac- 
ter). 


I  CTRL  I 


A  control  key. 


I  BREAK  I  or 

rcTRLirri 


Stops  the  current  program  execution. 


B  or 

fcrnirm 


Wsvm  the  cursor  to  the  left  one  space. 
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CTRL  - 


CTRL 


CTRL 


CTRL  3 


CTRL  / 


CTRL  BREAK 


r  SHIFT  BREAK 


or  rcTRLirci 


I  SHIFT  II  CLEAR  P 


[  CTRL  II  CLEAR  I 


SHIR 


or 


rCTlLirBI 


CTRL  1 


rcTRLirTi 


CTRL  8 


Generates  an  underscore  character. 

Generates  a  left  brace  ({). 

Generates  a  right  brace  (}). 

Generates  a  tilde  ("). 

Generates  a  backslash  (  \  ). 

Performs  an  ESCAPE  function,  and 
sends  an  end-of-ffll#  ffieiSaps  t©  a  pro- 
gram receiving  keyboard  input.  To  be 
recognized,  |  ctrl  ||  break  |  must  be  the 
first  thing  typed  on  a  line. 

Performs  a  CONTROL  C  function  by 
interrupting  the  video  displ^  of  a  pro- 
gram. The  program  mm  m  a  back- 
ground task. 

Selects  the  next  ¥Meo  i$tefik#. 

Selects  the  previous  w^Sm  ^Kindflfw. 

*  You  must  have  established  windows 
for  this  function  key  to  have  any 
effect.  See  "Using  Windows"  in 
Chapter  7. 

Toggles  the  keyboard  mouse  ou  and  off. 
The  keyboard  mouse  uses  the  arrow 
keys  and  the  two  function  keys  (Fl 
and  F2)  to  simulate  an  external 
mouse.  When  keyboard  mouft%  ii  on, 
the  normal  functions  for  the  arrow  and 
function  keys  is  suspended. 

Deletes  the  current  line. 


Activates  or  deactivates  the  shift  lock 
function. 

Generates  a  vertical  bar  (|). 
Generates  an  up  arrow  ("). 
Generates  a  left  bracket  ([). 
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I  CTRL  IIT]  Generates  a  right  bracket  ( ] ). 

I  CTRL  IITI  Redisplays  the  last  line  you  typed  and 

posflicraB  the  eursar  at  the  end  of  thB 
line,  but  does  not  process  the  line. 
Press  I  ENTER  I  to  process  the  line,  or  edit 
the  line  by  backspacing.  If  you  edit, 
press  I  CTRL  \[a]  again  to  display  the 
editeilhii* 

j  'CTRl.  IfTl  Redisplays  the  current  command  line. 

I  CTRL  Ifwl  Itemporarily  halts  video  output.  Press 

any      to  resume  output. 

I  ENTER  I  Performs  a  carriage  return  or  essecutes 

the  current  command  line. 
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"Sou  now  know  about  a  number  of  OS-9  commands  that  can  help 
you  set  up  use  ymx  computer  ^stem.  Tbme  are  imxiy  moire 
commands  available.  This  chapter  contains  ittfcrmation  about  a 

few  of  the  most  helpful  commands.  Becoming  acquainted  with 
these  makes  it  easy  for  you  to  use  other  commands  and  func- 
tions. OS-9  Commands  contains  more  information  and  a  com- 
plete reference  to  all  OS-9  coimnands  (including  those  you  have 
already  discussed). 

Viewing  Directories 

To  look  at  your  disk  directories  use  the  DIR  command.  For  exam- 
ple, to  view  the  contents  of  the  current  data  directory,  type: 

dir  I  ENTER  | 

If  your  data  directory  contains  more  filenames  than  can  display 
m  the  acmm  at  one  tiine,  Hie  Msj^^  pcuses.  Press  the  space  bar 
to  cause  additional  files  to  scroll  mto  tibe  soi^en. 

You  can  also  view  your  execution  directory  in  a  similar  manner. 
This  time  you  must  include  the  command  option,  x.  Type: 

dir    X  I  ENTER  | 

If  you  want  to  look  at  a  directory  on  a  disk  drive  other  than  the 
current  drive,  specify  a  complete  path  for  OS-9  to  follow,  includ- 
ing the  disk  drive  name.  For  example: 

dir  /dg/FftWILY/MQRK  |  ENTER  | 

Creating  Directories 

Before  you  can  store  data  In  a  directory  other  than  the  ROOT 

directory,  you  must  create  that  directory  with  MAKDIR.  For 
instance,  to  create  a  FAMILY  directory  on  your  Drive  /DO 
diskette,  type: 

makdir  /d0/FftMILY  T ENTER  | 
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Deleting  Directories 

You  can  also  delete  directories  you  create.  When  you  delete  a 
directory  you  also  delete  any  files  or  subdirectories  it  con- 
tains; so  use  this  conunand  with  caution.  To  delete  a  direc- 
tory, follow  these  steps. 

1.  Use  DIR  to  view  the  contents  of  the  target  directory  and  any  of 
its  subdirectories. 

2.  Copy  any  files  you  mnt  to  keep  into  a  iitectory  outside  th® 
directory  you  want  to  delete. 

3.  lype: 

d e  1  d  1  r  d,l rname- \M^M I. 
where  dimame  is  the  name  of  the  directory  you  want  to  delete. 
The  screen  sho»s: 

Deleting   directory  file. 

List   directory,   delete  directory,   or   quit  ? 
tl/d/'q) 

4.  "&U  now  have  three  options: 

a.  To  again  confirm  the  contents  of  the  directory  brfore  you 
delete  it,  press  Q]  |  enter  |. 

b.  To  initiate  the  deletion  process,  press  |T|  |  enter  |. 

c.  To  quit  the  process  and  leave  the  directory  intact,  press  H 

I  enteVi. 

If  you  try  to  delete  directories  other  than  the  ones  you  create, 
OS-9  might  display  Error  #214,  No  Permission  (you  do  not  own 
the  directory  or  have  write  permission  for  it).  For  information  on 
handling  such  directories,  see  the  ATTR  command  in  08-9 
Commands. 

Displaying  Current  Directories 

There  are  times  when  you  need  to  know  the  names  of  your  cur- 
rent data  and  execution  directories.  The  PWD  and  PXD  com- 
mands make  this  possible.  To  determine  your  current  data 
direil^j  lype: 


pwd  lENTEB  I 
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The  command  displays  the  path  from  the  ROOT  directory  to  the 
eiXTFetit  data  directory.  Iter  iitslamev  if  faur  eiirrent  data  direc- 
tory is  PLEASURE  (see  Figure  4.5  in  Chapter  4)  the  display  is: 

/D0/FAMILY/PLEASURE 

To  discover  your  current  elocution  directory,  tj^pe: 

pxd  I  ENTER  I 

The  might  display: 

/D0/CMDS 

A  standard  convention  of  OS-9  is  to  capitalize  directory  names.  If 
you  follow  this  convention  when  creating  directories,  you  can 
alwi^s  tell  which  files  are  directories  at  a  glance. 

Copying  Files 

COPY,  like  BACKUP,  provide  file  seciu-ity.  If  something  hap- 
pens to  one  file,  you  can  use  a  copy.  Also,  you  might  want  to  copy 
a  command  or  program  to  use  in  more  than  one  directory,  or  you 
might  want  to  use  the  same  data  on  more  than  one  computer. 

Suppose  you  are  in  the  PLEASURE  directory  of  a  diskette  confi- 
gured as  in  FigOF©  Your  execution  ilfettef  is  the  MMILY 
directory,  where  you  are  using  the  Expenses  program.  Because 
the  EAMILY  directory  does  not  contain  any  OS-9  commands,  you 
have  to  change  the  execution  directories  vAirniev&c  you  want  to  use 
them. 

You  can  make  your  work  easier  by  copying  the  Expenses  pro- 
gram to  tie  CMDS  direetory.  %  do  this,  first  the  CMDS 
directory  your  data  directory  hy  tjrping: 

chd   /dB/CMDS  |  ENTER  | 

Then        the  Bxp&ams,  file  to  the  CMDS  directory  by  typing: 

copy  /dB/FAMILY/expenses   expenses  |  ENTER] 

Now,  Expenses  is  in  the  CMDS  directory,  and  you  do  not  need  to 
change  the  execution  directory  to  FAMILY  to  use  it. 
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Likewise,  if  the  ROOT  directory  is  your  data  directory,  and  you 
vwrri;  to  csEy  &e  Mom  file  fitan  the  WORK  directory  to  the  ROOT 
directory,  tj^pe: 

copy  family/work /mom  mom  |  ENTER] 

You  can  copy  any  file  between  directories  and  between  disks.  To 
do  so,  you  must  provide  the  COPY  command  with  a  pathlist  for 
the  location  of  the  original  file  and  for  the  destination  of  its  copy. 

Deletiiig  FUes 

%u  can  delete  files  in  ai^  directory  using  the  DEL  command, 
su^h  as: 

del   myf  i  le  |  ENTER  | 

Yju  can  delete  a  file  in  the  current  execution  directory  by  using 
the  —X  parameter.  Bbr  instance,  to  delete  Myprogram  from  the 
current  execution  directory,  type: 

del   -X  myprogram  [ENTER  | 

If  the  file  ym  want  to  delete  is  in  a  directory  other  than  the  cur- 
rent data  directory  or  the  current  execution  directory,  you  must 
specify  the  full  pathlist  to  the  file.  For  instance,  suppose  you  are 
in  the  ROOT  directory  of  a  diskette  configured  as  Figure  4.5.  To 
delete  the  Joe  file  in  tihe  WORK  directory,  tj^e: 

del  family/work/joe  flNTERl 

If  the  file  you  want  to  delete  is  on  a  drive  other  than  your  cur- 
rent drive,  include  the  drive  name  in  your  pathlist,  such  as: 

del    /d1  /  f  ami  ly/wor  k  /  i  oe  |  ENTER  | 

If  you  attempt  to  delete  a  file  you  did  not  create,  OS-9  might  dis- 
idagr  Error  #214,  No  flra^^ba.  lb-  itAattaite  m  Me^^  such 
files  see  the  ATTR  command  in  OS-9  Commands. 

Renaming  Files 

OS-9  lets  you  change  the  names  of  files.  Suppose  Joe  leaves  home, 
and  you  now  want  to  keep  track  of  expenses  for  Sue.  To  change 
liie  name  of  the  Joe  file  to  Sue,  type: 

rename  family/pleasure/joe     sue  |  ENTER  | 


ft4 


OS-9  Toolkit  I  6 


Looking  Inside  Files 

LIST  is  a  command  that  lets  you  examine  files  that  consist  of  text 
characters.  5br  instance,  to  view  the  Dad  file  from  tfaie  WORK 
directory,  you  might  type: 

list  family/work /dad  [ENTER  | 

The  contents  of  the  file  appears  on  the  screen. 

If  you  use  LIST  to  display  a  file  that  Is  not  a  t^t  file,  it  pro- 
duces a  meaningless  display. 

Loading  Command  Modules  into  Memory 

When  using  OS-9,  you  might  notice  that  some  commands  begin 
^ecution  immediately,  while  others  require  access  to  the  disk 
drive  before  they  execute.  The  OS-9  commands  you  need  most 
often  load  into  memory  at  startup,  so  they  are  available  for 
immediate  use.  If  you  plan  to  frequently  use  a  command  that  is 
not  in  memory,  you  can  load  it. 

Esr  instance,  the  DSiWE  command  lets  you  copy  an  entire  direc- 
tory from  one  disk  to  another.  To  place  the  DSAVE  module  into 
your  computer's  memory,  first  be  sure  your  execution  directory  is 
the  CMDS  directory,  thrai  type: 

load  dsave  [  ENTER  | 

Now  you  can  use  DSAVE  as  many  times  as  you  want,  withotit 
waiting  for  OS-9  to  find  it  on  disk. 

Listing  the  Commaxtd  Mbdlil^  in  Memory 

At  startup,  OS-9  loads  Into  memory  the  commands  5^u  use  most 
often.  If  you  are  not  sure  whether  a  command  already  resides  in 
memory,  you  can  check  using  the  MDIR  command.  To  display  a 
directory  of  the  modules  in  your  computer's  memory  ,  type: 

mdir  |  ENTER  | 

A  list  of  all  the  modules  in  your  computer's  memory  appear  on 
the  screen.  The  names  you  see  are  of  modules  OS-9  uses  to  boot 
and  handle  system  operations  and  the  commands  it  loads  into 
memory  when  you  boot  the  system. 
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Deleting  Modules  from  Memory 

After  ym  had  a  mpdiile  iixtg  m^mt^f  also  d^te  it  Tbie 

process  is  eallM  nmMMMmg.  Tb  idbtie  tiie  DS^tfE  cwmumd  tmn. 
memory,  type: 

unlink  DSAVE  |  ENTER  | 

Some  modules  might  require  unlinking  more  than  once,  depend- 
ing on  the  number  of  times  they  were  linked. 

Do  not  attempt  to  unlink  modules  that  you  did  not  install  in 
memory  with  the  LOAD  command. 

Using  Other  Commands 

OS-9  has  nearly  50  commands  and  functions.  This  chapter  has 
mentioned  only  a  few.  Not  only  are  there  other  commands  avail- 
able through  OS-9,  several  of  the  commands  presented  here  have 
additional  options. 

The  guidelines  you  learned  in  this  handbook  provide  the  back- 
ground ym  need  to  make  use  of  0S<-9's  many  otliar  capabilities. 

By  referring  to  OS-9  Commands  you  can  learn  how  to  create 
files,  create  procedure  files  to  accomplish  complicated  tasks,  SSnd 
VE^rxmtioxi.  to  your  printer,  transfer  data  between  devices,  He- 
cate mmm  thaa  mm  iniik  at  tihe  mam  Mnw^,  &mi  wmh.  wfsce. 
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Your  OS-9  operating  system  is  originally  configured  in  a  certain 
way.  For  instance,  it  is  set  up  to  recognize  two  floppy  disk  drives, 
but  no  hard  drives.  It  is  set  up  to  recognize  a  printo"  or  one  egixs. 
terminal.  It  does  not  recognize  a  modem.  It  assumes  that  you  only 
want  32  characters  across  your  computer's  display  screrai.  It  pro- 
vides all  of  the  OS-9  commands. 

Using  the  CONFIG  utility  from  the  BASIC09/CONFIG  diskette 
that  came  with  your  OS-9  package,  you  can  create  system 
diskettes  that  raatch  the  coffliputer  systeni  yoii  Bave.  Before  pro- 
ceeding farther,  be  sure  you  have  a  working  copy  of  the  BASIC09/ 
CONFIG  diskette  and  a  blank,  formatted  diskette.  You  can  use 
the  instructions  in  "Making  Copies  of  Diskettes"  in  Chapter  3  to 
create  a  working  copy  of  the  BASIC09/CONFIG  diskette  and  to 
create  a  Iflartk,  formatted  dinette. 

Creating  a  New  System  Diskette 

To  create  a  new  system  diskette  make  sure  you  have  a  newly 
formatted  diskette  on  hand,  then  follow  these  steps: 

1.  Take  out  the  System  Master  diskette,  and  replace  it  with  the 
BASIC09/CONFIG  diskette.  Type: 

ehx  /da  /cmds  |  ENTER] 
chd   /d0  I  ENTER  I 
qonf  ig  |  ENTER  | 

TbB  tat  question  the  sereea  a  As  is: 

HOW  MPiNY  DRIVES  DO  YOU  HflVEs 

1  -   ONE  DRIVE  DNLY 

2  -  TWO   DR  MORE  DRIVES 

SELECTION  C1 ,21 

2.  If  you're  using  a  single-drive  system,  press  [T].  If  yOu  have 
more  than  one  drive,  press  (T). 

If  you  indicated  that  you  have  two  or  more  drives,  CONFIG 
prompts: 

EWTER  mm  OF  SOUieE  BISK: 
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and 

ENTER   NAME  OF  DEST.  DISK: 

Type  the  appropriate  drive  name  (/DO,  /Dl,  etc.)  at  each 
prompt. 

3.        informs  you  that  it  is: 

BUILDING  DESCRIPTOR  LIST 
....    PLEASE  WAIT 

OS-9  is  putting  together  a  list  of  the  various  devices  you 
might  want  to  use  with  your  computer.  When  it  fliaighes,  it 
shows  you  the  list: 

CDNFIG 

ARROWS   -  UP/DDWN/MDRE/BACK 
S  -  SEL/UNSEL  H  -  HELP  D  -  DONE 
ITEM  BEL 


P 

T1 
T2 

T3: 

Ml 

M2 

PIPE 

D0_3BS  X 

D1_35S 

D2_35S 
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To  view  the  rest  of  IMs  menu,  press  @-  Now  the  screen 

shows: 

CDNF  IG 

ARROWS   -  UP/DOWN/MDRE/BACK 
S  -  SEL/UNSEL  H  -  HELP  D  -  DONE 
ITEM  SEL 


D3_35S 

DDD0_35S 

D0_40D 

D1_40D 

D2_40D 

DDD0_40D 

D1_80D 

D2_80D 

4.  %u  can  choose  the  various  devices  you  plan  to  use  with  your 
computer  from  this  list.  To  choose  a  device,  use  [T]  or  {T}  to 
move  to  the  device.  The  -••  shows  the  device  you've  chosen. 
Then,  press  [s]  (for  Select)  to  display  an  X  in  the  SEL 
("Selected")  column.  Pressing  [|]  again  cancels  the  selection. 

"Kwi  can  move  back  and  forth  between  the  first  and  second 
screens  by  pressing  either  (from  the  first  screen)  or 
(from  the  second  screen).  Here's  a  short  description  of  each 
device  listed  on  this  screen.  To  display  helpful  information 
about  a  device,  position  the  on  its  hue  in  the  list,  and  press 
[h]  ^r  Wp.  "mmy  press  the  spaee  Iwr  to  make  ttw  hdp 
information  13m  deviises  on  %m  mtmax  aire: 

P  A  printer  that  connects  to  tihe  RS-232  smal  port 

on  your  computer. 

Tl  A  terminal  using  the  standard  RS-232  port  (in 

addition  to  your  main  computer  display). 

T2  A  terminal  using  the  optional  RS-232  commu- 

nications pak  in  Slot  1  of  the  Multi-pak  Inter- 
ftice.  T2  suppnis  a  full  baud  rate  range.  Um  T2 
in  addition  to  your  main  computer  display  alone, 
or  in  addition  to  your  main  computer  display  and 
a  'Tl"  type  termmal. 
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T3  Aaother  terminal  using  the  optional  RS-232 

communications  pak  in  Slot  2  of  the  Multi-pak 
Interfece. 

Ml  A  modem  using  an  optional  300  baud  modem 

pak. 

M2  A  modem  using  an  optional  300  baud  modem 

pak. 

PIPE  Lets  you  use  the  PIPE  utility  In  OWS  (a  utility 

that  takes  the  information  a  program  puts  out 
and  uses  it  as  input  data  in  another  command). 

D0_35S  Floppy  Disk  Drive  /DO,  single  sided,  35  tracks. 

D1_35S  Floppy  Disk  Drive  /Dl,  single  sided,  35  tracks. 

D2_35S  Floppy  Disk  Drive  /D2,  single  sided,  35  tracks. 

D3_35S  Floppy  Disk  Drive  /D3,  single  sided,  35  tracks. 

DBDOLjiiS  Default  Disk  Drive  /DD  using  Drive  /DO,  single 
sided,  35  tracks.  Select  one  default  drive  —  the 
drive  where  you  keep  your  system  diskette. 

D0_40D  Floppy  Disk  Drive  /DO,  double  sided,  40 
cylinders. 

D1-40D  Floppy  Disk  Drive  /Dl,  double  sided,  40 
cylinders. 

n2_4GD  Floppy  Disk  Drive  /D2,  double  sided,  40 
cylinders. 

DDD0_40D  Default  Disk  Drive  /DD  using  Drive  /DO,  double 
sided,  40  cylinders.  Select  one  default  drive  — 
the  drive  where  you  keep  your  system  diskette. 

D1_80D  Floppy  Disk  Drive  /Dl,  double  sided,  80 
cylinders. 

D2^S0D  Floppy  Disk  Drive  /D2,  double  sided,  80 
cylinders. 
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You  must  select  a  "DO"  device  as  your  first  disk  drive — use 
Dl,  Di,  and  DS  devices  ftr  aidMbmil  fl(^py  disk  drives.  Select 
the  drive  that  matches  the  drives  you  have  on  your  system.  If 
you  are  not  sure,  check  with  your  supplier.  To  use  extra  ter- 
minals aM  modems,  you  must  connect  them  via  a  Multi-Pak 
Interface. 

5.  As  you  finish  choosing  among  the  devices  on  the  first  screen, 
press  Q  to  display  another  screen  of  devices: 

6.  When  you  finish  selecting  devices,  press  [d]  for  Dwi.  11® 
screen  asks: 

ARE  YOU  SURE  CY/N)  ? 

7.  Now's  your  chance  to  change  your  mind.  Press  (T)  if  you  want 
to  reselect  your  devices.  If  you're  sure  about  the  devices  you 
selected,  press  (Y|. 

The  nejEt  part  trfthe  CONFIG  process  appears  on  the  screen: 
GDNFIG 

SELECT  TBTRM  DESiRI  PTDt 

1  -  TERM_VDG 

2  -  TIRM_WIN 

H  -  HELP 
SELECTION   El ,2] 

8.  These  are  Color  Computer  terminal  I/O  subroutine  modules 
you  can  use.  For  a  32  character  display,  select  1  (TERM_ 
VDG).  In  order  to  have  OS-9  windows  and  an  80  column  dis- 
play, select  2  (TERM_WIN). 

Note:  Ym  can  use  T1HM.WIN  Mttt  a  W  raliier  than 
a  monitor  but  it  is  difficult,  if  not  impossible,  to  see 
characters  on  an  80-column  window.  When  you  later 
create  tsKt  windows,  select  40-coltunn  displays. 
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If  you  select  2  (Term-Win),  CONFIG  presents  you  with 
am^ssat  mma  of  chraees.  This  fime,  tibe  disj^^  iKte  like 
this: 

CONFIG 

ARRDNS  -  UP/DDWN/MDRE/BACK 
S  -  SEL/UNSEL  H  -  HELP  D  -  DONE 
ITEM  SEL 


M  X 

W1  X 

m 
m 

M4 
MS 
M6 
W7 

This  list  represents  the  pre>«stablished  windows  you  can 
open  for  use  with  OS-9.  The  next  section  in  this  chapter  tells 
you  how  to  open  and  use  windows.  For  now,  if  you  expect  to 
open  windows  in  which  you  can  run  mulitple  tasks,  select 
these  items  for  your  new  diskette.  (See  "Using  Windows" 
later  in  this  Chapte.) 

9.  After  you  select  the  modales  you  want  to  use,  press  [¥}.  As  it 

did  when  you  selected  devices,  the  screen  asks  ARE  YOU 
SURE  CY/N)  ?  Press  (Y)  if  you're  finished.  Or,  press  [T|  to 
keep  working  on  this  screen. 

OS-9  creates  a  file  called  Bootlist  in  Drive  /DO's  ROOT 
directory,  using  the  information  you've  provided  so  far.  It  lets 
you  know  what  it's  up  iso  l[y  ^spfe^ing: 

BUILDING  BOOT  LIST 
,  , , .   PLEASE  WAIT 

Then,  1^  scsam.  asks: 

SELECT  CLOCK  MODULE: 

1  -  60   HZ  CAMERICAN  POWER) 

2  -   50   HZ  (EUROPEAN  POWER) 

SELECTION  [1,2] 

10.  Press  (T]  if  you  live  in  the  United  States,  Canada,  or  any 
other  country  that  uses  60Hz  electrical  power.  If  you  live  in 
a  country  that  uses  50Hz  electrical  power,  press  {J}. 
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11.  CONFIG  is  ready  to  begin  creating  your  customized  System 
Master  didcette.  If  jm.  hsm  tme  dill*©,  the  screea  Mli  you 
that  the  DESTINATION  diskette  is  your  blank,  formatted 
diskette  and  that  your  SOURCE  diskette  is  the  BASIC09/ 
CONFIG  diskette.  Place  your  formatted  diskette  in  the  drive, 
and  press  [c].  You'll  swap  between  the  formatted  diskette 
and  the  BASIC09/CONFIG  diskette  several  times. 

If  you  have  a  two-drive  system,  place  a  fimmatted  diskette  in 
Drive  /Dl,  and  press  the  space  bar.  The  screen  tells  you  that 
OS-9  is: 

GENERATING  MEN  BOOT 
....   PLEASE  WAIT 

12.  Ebllowing  the  boot  file  generation,  a  menu  lets  you  select  the 
commands  you  want  to  include  on  your  system  diskette.  You 
have  the  following  choices:  none;  the  full  set  of  commands;  or 
a  set  consisting  of  commands  you  choose  individually.  The 
menu  looks  like  this: 

CONFIG 

DO  YOU  WISH  TO  ADD 
[N]D  COMMANDS,   STOP  NOW 

[F3ULL   COMMAND  SET 
[ I  INDIVIDUALLY  SELECT 
im  RfeEIVE  HELP 
SELECTION  [N,F,I,H] 

Most  people  like  to  choose  the  individual  commands  they 
want  to  use.  For  the  time  being,  press  [T]  to  include  the  full 
set.  Later,  you  can  create  another  custom  didtette  that  has 
only  the  commands  you  need. 
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13.  Do  one  of  the  following: 

a.  If  you  have  one  drive,  the  screen  asks  you  to  place  your 
formatted  di^tte  in  Drive  /DO.  Do  so,  and  press  the 

space  bar.  Next,  you'll  place  your  "uncustomized"  backup 
of  the  System  Master  diskette  in  Drive  /DO.  Swap  the  two 
dis^ttes  as  the  screen  asks  you  to.  When  the  CONFIG 
farogram  finishes,  the  0S9:  message  reappears.  "&u  now 
have  a  brand  wm,  eostomized  copy  of  the  Systan  Master 
dyMie* 

b.  If  you  have  more  than  one  drive,  the  screen  asks  you  to 
place  yoiu-  system  diskette  in  Drive  /DO.  CONFIG  contin- 
tm  smi  to  a  §m  minutes,  finishes  its  work.  The  osS: 
message  reappeara,  and  you  have  a  customized  copy  of  the 
System  Master  diskette  in  Drive  ^1. 

14.  Label  the  diskette  so  that  you  can  distingui^  between  your 
working  copy  of  the  System  Master  diskette  and  the  custom 
copy. 

Monitor  l^pes 

OS-9  lets  you  set  your  system  for  different  monitor  types.  The 

monitor  options  are  for  a  RGB  color  monitor,  a  composite  color 
monitor  or  TV,  or  a  monochrome  monitor  or  TV.  To  set  your  sys- 
tem for  a  particular  monitor  type,  enter  one  of  the  following  com- 
mands, or  add  it  to  your  system  Startup  file: 

Monitor  Type  Command 

RGB  montype  r 

Composite  montype  c 

Monochrome  monts^pe  m 

Therefore,  to  set  your  Systran  for  a  composite  monitor,  type: 

montype   c  |  ENTER  | 

lb  save  typing  the  command  each  time  you  start  OS-9,  put  it  in 
the  Starfei®  ffle  in  the  ROOT  direotey  A  your  system  diskette. 

If        s^fitaEiL  dJsk  does  not  have  an  existing  Startup  file: 

Create  am  l^^pifflg: 

build  startup  ["IntIrI 
montype  r  |  ENTER  | 

[enterI 
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If  your  system  4^ek.  sdread^  1:^  a  Startup  iBle: 
First  rename  the  Startup  file  Ijy  typing: 
reTtarae  a  tar  tup  oldatart  [JNIIR I 
Then  create  a  file  that  contains  the  new  command,  such  as: 

build  news  tart  |  ENTER  | 
montype   r  |  ENTER  | 
flNTlBl 

Now  combine  the  two  files  into  a  new  Startup  file: 

merge  oldstart  newstart  >  startup  | ENTER | 

Use  DEL  to  delete  oldstart,  newstart,  or  both,  or  leave  them  on 
your  disk  for  future  use. 

Using  Windows 

If  the  window  descriptors  (W,  Wl,  W2,  W3,  W4,  W5,  W6,  W7) 

and  the  graphics  interface  and  driver,  Grflnt  and  GrfDrv,  are  in 
memory,  OS-9  lets  you  set  up  windows  on  your  display  screen. 

Note:  Grflnt  and  the  window  descriptors  must  be  loaded  as 
part  of  the  boot  operation.  %iir  S|ystem  Master  diskette  does 

Once  you  have  initialized  windows,  you  can  then  move  among 
them,  initiating  different  tasks  in  each.  %u  can  even  have  differ- 
ent processes  showing  on  dififerrait  portions  of  your  display  screen 

at  the  same  time. 

Another  advantage  of  using  windows  is  that  you  can  choose  win- 
dows that  give  you  displays  of  40  or  80  columns  across  the  screen, 
rather  than  only  32.  However,  unless  you  have  a  monitor  con- 
nected to  your  computer,  rather  than  a  television,  you  might  be 
unable  to  read  the  screen. 

Establishing  a  Window 

Y)u  can  establish  one  or  more  windows  after  booting  OS-9,  or  you 
can  include  the  window  cr^Mon  larocess  in  OS-9's  Startup  file. 
Startup  is  a  file  containing  commands  you  want  your  system  to 
execute  during  startup. 
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To  establish  a  ttma  fte  OS-9  prompt,  type: 

iniz  wnumber  |  ENTER  | 
shell    1  = /w  numfaer&  [enter] 

In  this  example,  number  represents  the  window  number  to  ini- 
tialize. After  you  type  these  commands,  you  can  select  the  win- 
dow by  pressing  |  clear  |.  To  return  to  the  original  screen,  fffess 

The  drfault  -mhsm  for  tibe  wmhm  descriptes  JWl  '&mE^h.  JW! 
are: 


Window 

Text  size 

Window's  physical  size 

device  name 

in  columns 

Starts  at: 

Size: 

fWl 

40 

0,0 

27,11 

AV2 

40 

28,0 

12,11 

AV3 

40 

0,12 

40,12 

AV4 

80 

0,0 

60,11 

AV5 

80 

60,0 

19,11 

/W6 

SO 

80,0 

80,12 

/W7 

80 

0,0 

80,24 

Note:  lb  initialize  Windows  AV2  and  fW3,  you  must 
be  operating  from  Window  /Wl.  To  create  Windows 
AV5  and  /W6,  you  must  be  operating  from  Window 
/W4. 

The  "Starts  at"  column,  indicates  the  position  on  the  screen  of  the 
top  left  comer  of  the  window.  On  the  screen  grid,  coordinates  0,0 
are  located  at  the  top  left  comer. 

Tim  '*^s&f  mhmm.  UlKtei  te  £icmEibi^  GS  ihstmlxm  me^  @ach 

Therefore,  Window  1  displays  40  column  text,  begins  in  the  top 
left  comer  of  the  screen,  extends  right  for  27  characters  and  down 
for  11  lines.  Window  5  displays  80  column  text,  begins  at  the  top 
of  the  screen,  60  colvunns  from  the  left,  extends  19  colvmms  to  the 
jifht  and  11  lines  down. 

Note  that  the  coordinates  for  each  window  are  based  m.  the  text 
size  of  the  screen.  Therefore,  Window  1  Qiased  on  40  column  text) 
ends  at  column  27,  while  Window  5  (based  on  80  column  text) 
begins  at  column  60. 
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Using  the  information  in  the  previous  chart,  you  can  now  estab- 
lish any,  or  all,  of  the  seven  windows. 

Note:  Ifou  cannot  establish  all  of  the  windows  unless  your 
computer  has  512  kilobytes  of  memory. 

Pbr  instance,  to  set  up  a  full  screen,  80-column  window,  type: 

shell    i  =  /w7&  |  ENTER  | 

After  a  short  pause,  the  screen  displays  a  message,  such  as: 

This  means  that  OS-9  has  opened  a  path  to  your  new  window  and 
started  a  shell  on  the  window  wi^  tfe  process  idetttffleatiati  of  04. 
To  move  to  the  window,  press  |  clear  |.  Your  32-column  screen  van- 
ishes and  you  are  now  in  Window  7.  You  can  type  commands  or 
run  programs  from  here  in  the  same  manner  as  he^re. 

To  set  up  three  windows  on  the  same  screen,  type  these  com- 
mands, then  use  |  clear  |  to  move  among  the  windows: 

iniz  w1    w2  w3  |  ENTER  | 
shel  l    i  =  /w1  4  I  ENTER  I 
shel  1    i  =  /w2&  |  ENTER  | 
shell    i  =  /w3&  |  ENTER  | 

If  you  want,  and  your  computer  has  enough  memory,  you  can  run 
different  processes  in  aiU  of  the  windows. 

Changing  Window  Colors 

Perhaps  you  don't  like  the  color  of  the  screen  in  one  or  more  of 
your  windows.  You  can  change  it  using  the  display  command.  The 
following  charts  show  you  all  of  the  colors  available  for  the  screen 
backgroimd,  text,  and  border. 
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Background  Code  =  33 
Ttext  Code  =  32 
Bcsrder  Code  =  34 


Color  Codes 


Codes 


Color 


00  or  08 

01  or  09 

02  or  OA 

03  or  OB 

04  or  OC 

05  or  OD 

06  or  OE 

07  or  OF 


White 

Blue 

Black 

Green 

Red 

Yellow 


Magenta 
Cyan 


To  change  a  color,  t3^e  DISPLAY  lb,  followed  by  the  background, 
test,  border,  or  fbreground  code  followed  by  a  color  code.  Then, 
press  I  ENTER  I. 

For  instance,  if  you  are  in  Window  7,  you  can  change  tlie  back- 
ground color  to  red,  by  typing: 

display  1b  33  04  |  ENTER  | 

Change  the  text  color  to  black  by  typing: 

display   lb   32   0  2  |  ENTER  | 

To  put  a  white  border  around  the  screen,  tj^e: 

display   lb   34   0  0  |  ENTER  | 

You  can  also  type  all  the  codes  on  one  line,  like  this: 

display  lb  33  04   lb  32  02   lb  34   0  0  |  ENTER  | 

Pick  the  colors  you  want  for  each  window,  and  change  them 
using  DISPLAY. 

Eliminatiiig  a  Window 

In  the  cojonnand  to  establish  windows  (shell  i=/wnumber&),  "i" 
tells  SHELL  that  the  process  being  created  is  immortal.  This 
means  that  yoii  can  only  terminate  it  from  the  window  in  wMeh 
it  resides. 
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To  kill  a  window  in  which  you  have  established  a  shell,  ptess 
I  CLEAR  I  until  the  window  you  want  appears  on  the  screen.  Type: 

ex  I  ENTER  | 

Now  press  |  clear  |  to  move  to  another  window  in  which  a  shell  is 
running.  Then  use  DEINIZ  to  deinitialize  that  window.  For 
instance,  if  the  window  you  want  to  eliminate  is  Window  1,  type: 

deiniz  w1  |  ENTER  | 

Using  Startup  lb  Mstablsih  A  Window 

If  you  intend  to  use  a  window  whenever  you  start  OS-9,  for 
instance  if  you  want  to  use  an  80  column  screen,  put  the  appro- 
priate commands  in  the  Startup  file.  This  file  must  be  located  in 
the  ROOT  directory  of  ymr  system  disk. 

If  your  system  diskette  idready  lias  a  Startup  fflle: 

First  rename  the  existing  Startup  file,  sxu;h  as: 

rename  startup  oldstart  |  ENTER  | 

Then  put  your  new  commands  into  a  temporary  file.  To  Initialize 
window  Number  7  (80  columns,  full  screen)  with  white  text  on  a 
black  background,  type: 

build   t  emp  s  tart 
ini  z  w7  I  ENTER  | 
shell    i  =  /w7&  I  ENTER  | 

display  lb  32  00  1b  33  02  lb  34  02  0o  >  M  CliMI 

Now  combine  your  new  commands  with  the  original  Startup  file 
by  typing: 

merge   oldstart    tempstart    >    startup  |  ENTER] 

YoM  can  remove  the  Tempstart  file  by  typing  del  tempstart 
I  ENTER  I.  or  yon  can  leave  it  in  your  ROOT  directory  for  fature  use. 
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U  lteiap  dues  not  already  exist: 
Create  it  by  typing: 

build   startup  |  ENTER  | 
iriz   w7  |  ENTER  | 

display  lb  32  0  0  lb  33  02  1b  34  02  0c  >  /w7  | ENTER | 
shell    i  =  /w7&  |  ENTER  | 

I enterI 

Now,  after  ym  boot  0§-9,  press  |  clear  |  to  operate  in  an  SO- 
column,  black  and  white  screen. 
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Chapter  1 


Introduction 


Getting  Started  With  OS -9  contains  the  information  you  must 
know  to  use  the  system.  However,  the  handbook  reveals  only  a 
isoall  firl  of  OS-f's  capabilities.  Tb  learn  about  all  of  its  fea- 
tures, you  wmi  to  know  more  about  how  OS-9  works.  This  intro- 
duction proi^Mes  such  basic  background  information. 

The  Kernel 

At  the  center  of  the  OS-9  system  is  a  module  (program)  called  a 
kernel.  (See  the  following  illustration.)  The  kernel  provides  basic 
system  services,  such  as  nrultitasking  and  memory  managenaettt. 
It  links  other  system  modules  and  serves  as  the  system  adminis- 
trator, supervisor,  and  resource  manager. 


Figure  1 

Term  is  your  keyboard  and  video. 
Tl  and  T2  are  additional  terminals. 

P  is  a  printer. 
Ml,  M2,  and  M3  are  modems. 
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The  Input/Output  Manager 

Although  the  kernel  manages  OS-9,  it  does  not  directly  process 
the  input  and  output  of  data  among  the  other  modules  and  your 
computer  hardware  (printers,  disk  drives,  terminals,  and  so  on). 
Instead  the  kernel  passes  this  responsibility  to  the  input/output 
manager,  lOMAN. 

lOMAN  has  three  submanagers:  a  character  file  manager,  a  pipe 
file  manage,  and  a  disk  file  manager.  The  responsibilities  of 

these  managers  are  as  follows: 


The  Character 
File  Manage 


The  Pipe  File 
Manager 

The  Disk  File 
Manager 


Handles  the  transfer  of  data  between  OS-9 
and  character  devices  (devices  that  operate 

on  a  character-by-character  basis,  such  as 
terminals,  printers,  or  modems).  The 
sequential  character  file  manager  (SCF)  can 
handle  any  number  or  type  of  such  devices. 

Handles  communication  between  processes 
or  tasks.  Pipes  let  you  use  the  output  of  one 
process  as  the  input  of  another  process. 

This  Random  Block  File  Manager  (RBF) 
handles  the  transf^  of  data  to  and  from 
bhch'&'tm^edi  rem^om  meess  devices,  sttch 
as  a  disk  drive  system. 


Device  Drivers 

CC3I0,  PIPER,  and  CC3DISK  are  device  drivers.  These  files  con- 
tain code  that  transforms  standard  data  into  a  form  acceptable 
to  a  particular  device,  whether  it  is  a  terminal,  printer,  modem, 
disk  drive,  any  other  device,  or  another  file.  PIPES  transfers 
data  between  processes. 

Term,  Tl,  P,  Ml,  DO,  and  so  on,  are  device  descriptors.  These 
files  describe  the  devices  connected  to  the  system.  They  contain 
device  initialization  data  as  well  as  code  that  directs  OS-9  to  the 
physical  addresses  of  the  ports  to  which  devices  are  connected. 
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The  Shell 

The  kernel,  m  cojgunctipn  with  lOMAN  and  its  associated  man- 
agisrs  and  modules,  maike  tip  the  OS-9  operating  system.  These 
modules  handle  all  of  the  system's  functions.  However,  OS-9 
needs  directions  before  it  can  accomplish  useful  tasks. 

Directions  to  the  system  have  two  sources:  commands  and  appli- 
cations or  computer  language  programs. 

Before  commands  are  useful  to  the  kernel,  the  shell  must  inter- 
pret them.  It  analyzes  commands  and  converts  them  into  code 
that  the  kernel  can  understand. 

Some  application  programs  and  computer  languages  also  use  the 
shell's  functions.  Others  can  access  the  kernel  directly  and  do  not 
need  to  go  through  the  shell. 

(Gbing  On 

Chapters  1  through  5  contain  fletailed  f nfermatton  on  the  opera- 
tion of  the  OS-9  system  illustrated  in  Figure  1.  These  chapters 
more  fully  describe  the  composition  of  files  and  directories.  They 
tell  about  advanced  ^tJttes  of  commands  and  of  the  shell  and 
contain  information  on  multiprogramming  and  memory 
management. 

Chapter  6  contains  descfiptlaas  of  the  OSri  commmnds.  Chapter 
7  tells  you  how  to  use  OS-9's  Macro  Text  Editor. 
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The  OS-9  File  System 


Input  and  output  refer  to  the  data  your  computer  system 
receives  and  the  data  that  it  sends.  OS-9  can  receive  (input) 
iata  from  a  keyboard,  disk  files,  modems,  and  other  terminals.  It 
can  send  (output)  data  to  all  of  these  (le\dces — except  the  key- 
boa^i — snet  to  a  vMbo  display. 

OS-9  receives  and  sends  data  in  the  same  fcrmat,  regardless  of 

whether  the  destination  is  a  file  or  a  device.  It  overcomes  the  dif- 
ferences in  the  devices  by  defining  a  standard  for  them  and  using 
device  drivers  to  make  each  deirie©  conform  to  the  standard.  The 
result:  a  much  simpler  and  more  versatile  input/output  system. 

Input/Output  Paths 

The  base  of  OS-9's  unified  I/O  system  is  an  organization  of 
paths.  Input/output  paths  are,  in  effect,  software  links  betwem 
files.  (Remember,  OS-9  thinks  of  all  devices  as  files.) 

Individual  device  drivers  process  data  so  that  it  conforms  to  the 
h8U"dware  requirements  of  the  device  inwlved.  Data  transte  is  in 
streams  of  8-bit  bytes  that  can  be  either  bidirectional  (read/ 
write)  or  unidirectional  (read  only  or  write  only),  depending  on 
the  device,  how  you  establish  the  path,  or  both.  A  byte  is  a  unit 
of  computer  data,  (A  byte  may  contain  the  code  for  one  alphabet 
cteraet^.)  A  lit  m  a  Mnary  digit  aad  hm  a  "^Mkm  either  0  or 
1. 

OS-9  does  not  require  the  data  it  manages  to  have  any  special 
format  or  meaning.  The  meaning  of  the  data  is  determined  by 
the  programs  that  use  it. 

Seme  of  the  advantages  of  sttch  a  unified  FO  systmi  are: 

•  Programs  operate  correctly  regardless  of  the  I/O  ^ivices 
selected. 

•  Programs  are  highly  portable  from  one  computer  to 
anowar,  eviai  when  the  computers  have  different  types  of 
FO  devices. 

•  'You  can  redirect  I/O  to  alternate  files  or  devices  when 
you  run  a  program,  without  having  to  alter  the  program. 
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•  You  can  easily  create  and  install  new  or  special  device 
driver  routines. 


Disik  Directoiies 

A  directory  is  a  storage  place  for  other  directories  and  files.  It 
contains  the  information  about  the  directories  and  files  assigned 
to  it  so  that  QBS  ean  easily  find  and  amm&  ^  data  they 
contain. 

Each  disk  has  its  own  directory  system.  For  example,  a  typical 
system  diskette,  diagrammed  partially  and  simply,  might  look 
like  this: 

DO  (Drive  /DO) 


/DO  ROOT  Directory 


V 
SYS 


Startup 


V 

CMDS 


V 

Errmsg 


copy 


Y 

list 


dir 


V 
del 


V 

format 


The  ROOT  directory  of  /DO— the  ROOT  from  which  the  rest  of 
the  disk's  file  system  grows — contains  a  file  called  Startup  and 
two  directories,  SYS  and  CMDS. 

SYS  and  CMDS,  in  turn,  contain  files:  SYS  contains  Errmsg, 
and  CMDS  contains  Copy,  List,  Dir,  Del,  and  Format.  All  these 
files  and  directories,  and  many  more,  come  built  into  the  OS-9 
systetn. 

OS-9  organizes  each  directory  area  into  32-byte  records.  The 
first  29  bj^es  contain  filename  characters.  The  first  byte  of  the 
name  has  its  sign  bit  (the  leftmost  or  most  significant  bit)  set. 
When  you  delete  a  file,  it  is  not  immediately  destroyed.  Rather, 
the  dtfiirtion  process  sets  the  first  character  position  of  the  record 
to  zm),  and  OS-9  no  longer  recognizes  the  record.  Although  the 
file  contents  still  exist,  they  are  no  longw  accessible  to  you  or 
OS-9.  ^ba^QiUl  file  creations  ovearwrite  deleted  records. 
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The  last  three  bytes  of  a  record  make  up  a  24-bit  binary  number 
that  is  the  logical  sector  number  pointing  to  the  file  descriptor 
record.  Logical  sectors  are  numbered  with  reference  to  the 
sequence  of  their  use,  rather  than  their  physical  location  on  a 
disk.  See  "Disk  Files"  for  more  information  on  disk  organization. 

You  create  directories  using  the  MAKDIR  command  and  can 
identify  them  by  the  D  (directory)  attribute.  (See  "Examining 
and  Changing  File  Attributes".)  MAKDIR  initializes  each  direc- 
tory with  two  entries  having  the  names  "."  and  These 
entries  contain  the  logical  sector  numbers  of  the  directory  and 
its  parent  directory,  respectively. 

You  cannot  use  the  COPY  and  LIST  commands  (as  described  in 
Getting  Started  With  OS-9)  with  directories.  Instead,  use  DSAVE 
and  DIR. 

"Skt  cannot  delete  directories  dfreetly.  "iju  must  first  empty  a 
directory  of  files,  convert  it  into  a  standard  file,  and  then  delete 
it.  However,  the  DELDIR  command  performs  all  these  functions 
automatically. 

Subdirectories 

A  subdirectory  is  a  directory  residing  in  another  directory. 
Actually,  all  directories  you  create  are  subdirectories,  since  all 
directories  branch  from  the  ROOT  directory.  However,  because 
the  ^lein  autematically  creates  the  ROOT  directory  whrai  you 
format  a  disk,  this  manual  does  not  consider  directories  residing 
in  the  ROOT  directory  to  be  subdirectories. 

Subdirectories  can  contain  files  and  other  subdirectories.  In 
effect,  OS-9  catalogues  files  and  directories  in  much  the  same 
way  that  you  might  put  files  pertaining  to  a  particular  subject 
in  a  file  cabinet  drawer.  With  OS-9,  you  can  have  as  many  direc- 
tory levels  as  your  disk  storage  space  permits. 

Disk  Files 

A  disk  file  is  a  logical  block  of  data.  (Logical  means  that 
although  the  data  might  not  actually  exist  in  a  contigUQtm  bteek^ 
OS-9  treats  it  as  though  it  does.)  A  file  can  contain  a  program;, 
text,  a  command,  a  computer  language,  or  any  other  form  of 
code.  Every  time  you  ask  OS-9  to  store  data  on  a  disk,  you  must 
specify  a  filename  for  that  block  of  data.  Both  you  and  the  sys- 
tem must  thrai  use  the  filename  to  access  the  data. 
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The  system  stores  all  files  as  an  ordered  sequence  of  8-bit  bytes. 
The  file  can  bf  amj  fiize  §eim  0  bytes  to  the  maximum  capacity 
of  the  stojrag©  Atvic®  and  can  be  expanded  or  shortened  as 
desired. 

When  OS-9  creates  or  opens  a  file,  it  establishes  a  file  pointer  for 
it.  OS-9  addresses  bytes  within  the  file  in  the  same  manner  it 
addresses  memory,  and  the  file  pointer  holds  the  address  of  the 
n^t  bjs^  10  "ssaiii  m  rmi,  QB^d's  read  ani  tm^  fy&dkm 
alw^i  update  ite  petet^  m  lis  sj^ten  transfers  data. 

This  pointer  function  lets  assembly-language  programmers  and 
high-level  language  programmers  reposition  the  file  pointer.  To 
expand  a  file,  write  past  the  previous  end  of  the  file.  Reading  up 
to  the  last  byti  of  a  file  causes  the  next  read  request  to  return 
an  eBd-of<-file  statnis. 

0S-9*s  file  system  also  uses  a  univef sal  orgattizatibh  for  all  I/O 

devices.  This  feature  means  that  application  programs  can  treat 
each  hardware  device  similarly.  The  following  section  gives  basic 
information  about  the  physical  file  structure  used  by  OS-9.  (For 
more  information,  see  the  OS-9  Level  Two  Technical  Reference 
manual.) 

Sectors 

The  data  contained  in  a  file  is  stored  in  one  or  more  sectors  (disk 
storage  units).  These  file  sectors  have  both  a  logical  and  a  physi- 
cal arrangement.  The  logical  arrangement  numbers  the  sectors 
in  sequence.  The  physical  arrangement  can  be  in  any  order 
based  on  the  actual  location  of  a  sector  on  a  disk's  surface,  fbr 
instance.  Logical  Sector  1  might  be  located  at  Physical  Sector 
10,  and  Logical  Sector  2  might  be  located  at  Physical  Sector  19. 

Each  sector  contains  256  data  bytes.  The  first  sector  of  every  file 
(Logical  Sector  Number  0  or  LSN  0)  is  called  the  file  descriptor. 
It  contains  the  logical  and  physical  description  of  the  file.  The 
disk  driver  module  links  sector  numbers  to  physical  track/sector 
numbers  on  a  disk. 

A  sector  is  the  smallest  physical  unit  of  a  file  that  OS-9  can 
allocate  for  storage.  On  the  Color  Computer,  a  sector  is  also  the 

smallest  file  unit.  (To  increase  efficiency  on  some  larger-capacity 
disk  systems,  OS-9  uses  uniform-sized  groups  of  sectors,  called 
clusters,  as  the  smallest  allocatable  unit.  A  cluster  is  always  £Ui 
integral  power  of  two — Q>,  4, 8,  and  so  on,) 
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OS-9  uses  one  or  more  sectors  of  each  disk  m  &  bitjaap  (usually 
starting  at  LSN  1)  in  which  each  data  Mt  coii'esponcls  to  one 
cluster  on  the  disk.  The  system  sets  and  clears  bits  to  indicate 
which  clusters  it  is  using,  which  clusters  are  defective,  and 
which  clusters  are  free  for  allocation.  The  OoloT  Computer 
default  floppy  disk  system  uses  this  format: 

•  Double-density  recording  ou  one  side 

•  35  tracks  per  diskette 

•  18  sectors  per  track 

•  One  sector  per  cluster 

jEach  OS-9  file  has  a  directory  entry  that  includes  the  fileaaroe 
and  th@  logical  sector  nvunber  of  the  file'a  flh  descrtptxjr  seetor. 
The  file  descriptor  sector  contains  a  complete  description  of  its 

file,  including: 

•  Attributes 

•  Owner 

•  Date  and  time  created 

•  Size 

•  Segment  list  (description  of  data  sector  blocks) 

Unless  the  file  size  is  0,  the  file  uses  one  or  more  sectors/clusters 
to  store  data.  The  system  groups  data  sectors  into  one  or  more 
adjacent  blocks  called  segments, 

Ifext  files  contain  variable-length  lines  of  ASCII  characters.  A 
carriage  return  (ASCII  code  OD  he^iadecimal  or  13  decimal)  ter- 
minates each  line.  Te^t  files  contain  such  data  as  program 
source  code,  procedure  files,  messages,  and  documentation. 

Programs  usually  read  text  files  sequentially.  Almost  aU  high- 
level  languages  (such  as  BASIC09)  support  text  files, 

Use  LIST  to  examine  the  content  of  text  files. 
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Random-Access  Data  Files 

Random-access  files  consist  of  sequences  of  records,  with  each 
record  the  same  lengtib.  A  program  can  find  any  record's  begin- 
ning address  by  multiplying  the  record  number  by  the  number  of 
bytes  used  for  each  record.  This  feature  allows  direct  access  of 
any  record. 

Usually,  high-level  languages  let  you  subdivide  records  into 
fields.  Each  field  can  have  a  fixed  length  and  use.  Ear  exam^e, 
the  first  field  of  a  record  can  he  i@  t@rt:  chsmeti&m  in  imgl^  the 
n^  field  can  be  two  bytes  in  length  and  used  to  hold  16-bit 
binary  numbers,  and  so  on. 

OS-9  does  not  directly  process  records.  It  only  provides  the  basic 
file  fune^ws  used  hy  high-levd  languages  to  create  and  handle 
r£tndomrai^sess  files. 

Frogearnxmrn  we  high-level  languages  like  BASIC09,  Pascal, 
and  C  to  create  random-access  data  files.  For  instance,  in 
BASIC09  and  Pascal,  GET,  PUT,  and  SEEK  functions  operate 
on  random-access  files. 

Pmmdwtm  Wiles 

Procedure  files  are  disk  files  that  contain  commands.  Yon  can 
use  them  to  execute  a  series  of  commands  by  typing  and  enter- 
ing a  single  command  name. 

Your  System  Mast^  ^^tte  mB^mm  one  procedure  file  named 
Startup.  You  can  create  your  mm  procedure  files  using  the 
BUILD  eommand,  copying  input  fi"om  the  keyboard  to  a  file,  or 
by  issiltg  A  text  editor  program.  For  instance,  suppose  you  have 
three  disk  drives,  /DO,  /Dl,  and  /HO.  You  could  create  three  very 
simple  procedures  to  allow  you  to  look  at  the  directoriw  df  these 
disks  by  typing  and  entering  a  simple  two-character  command. 

To  create  a  procedure  file  to  look  at  the  directory  of  /Dl,  type: 

build  pi  I  ENTER  | 
display  0C  |  ENTER  | 

dir   /dl  I  ENTER  | 
display  0A  |  ENTER  | 
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The  first  line  creates  a  file  named  PI  (print  directory  for  Drive 
/Dl).  When  you  press  |  enter  |,  a  question  mark  appears  on  the 
screen  telling  you  that  OS-9  is  waiting  for  input.  Type  the  rest 
of  the  lines.  Finally,  press  I  enter  |  at  the  beginning  of  a  line  to 
tell  OS-9  that  the  input  is  complete.  OS-9  closes  the  file. 

Now,  to  see  the  contents  of  Drive  /Dl,  tfpe  p  l  |  enter  |.  The  com- 
mand display  0C  dears  the  video  screen.  The  command 
display  0A  causes  the  cursor  to  drop  down  one  line  on  the 
screen. 

Use  your  imagination.  Almost  anything  you  can  do  from  the  key- 
board, you  can  do  with  a  procedure  file.  However,  remember  that 
OS-9  looks  only  in  the  current  data  directory  for  a  procedure 
file,  unless  you  provide  a  full  pathlist  to  the  procedure.  Also, 
OS-9  must  be  able  to  find  any  command  in  the  current  execution 
directory  that  is  part  of  a  procedure  file.  If  the  dUErent  eiecution 
directory  does  not  contain  the  commands  you  need,  change  it, 
either  from  the  keyboard  or  as  part  of  your  procedure  file. 

Executable  Program  Module  Files 

OS-9  program  modules  are  executable  program  code,  generated 
by  an  asSimblttP  or  compiled  by  a  high-level  language.  A  file  can 
contain  one  or  more  program  modules. 

Each  module  has  a  standard  format  that  includes  the  object  code 
(the  executable  portion  of  the  module),  a  module  header  that 
describes  the  type  and  size  of  the  module,  and  a  CKO  (Ojrclic 
Redundancy  Checksum)  value.  The  system  stores  program  mod- 
ules in  files  in  the  same  structure  in  which  they  load  into  mem- 
ory. Because  OS-9  programs  are  position-independent,  they  do 
not  require  specific  memory  addresses  for  loading. 

For  OS-9  to  load  program  module(s)  from  a  file,  the  file  execute 
attribute  must  be  set,  and  each  module  must  have  a  valid  mod- 
ule header  and  CRC  value.  If  you  or  the  system  alters  a  program 
module  in  any  way  (either  as  a  file  or  in  memory),  its  CRC 
check  value  becomes  incorrect,  and  OS-9  cannot  load  the  module. 

If  a  file  contains  two  or  more  modules,  OS-9  treats  them  as  a 
group  and  assigns  contiguous  memory  locations  for  them. 
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Using  LIST  on  program  files  or  any  other  files  that  contain 
binary  data,  causes  a  jumbled  display  of  random  characters  and 
an  ect&t  message. 

Miscellaneous  File  Use 

(M0§  "bm^  fflfe  ttinctions  are  so  versatile  that  you  can  devise 
aJsKSst  tZEtlilfiited  numbers  of  special-purpose  file  formats  for 
"psse^kx&m  applications  that  require  formats  not  discussed  here 
hmi,  random-access,  and  so  on). 

The  File  Security  System 

Each  file  and  directory  has  properties  called  ownership  and  attri- 
butes that  deiermiae  can.  areess  the  fite  mi  hm  Hai^  eas 
use  it. 

OS-9  autOJBSticaUy  stores  the  tis^  number  associated  with  the 
creation  cf  a  file.  The  system  considers  the  owner  ^  Ute  mtmb^ 
to  be  the  mm&  of  the  file. 

Security  functions  are  based  on  access  attributes.  There  are 
eight  attributes,  each  of  which  can  be  turned  off  or  on  indepen- 
dently. When  the  D  (directory)  attribute  is  on  for  a  file,  that  file 
is  a  directory.  (Only  MAKDIE  caiL  set  the  D  attribute  for  a  file.) 
When  the  S  (single-user)  atferfltafe  is  on,  only  one  program  or 
mee  earn  aeeess  ^  file  ai  a  f f me. 
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The  other  six  attributes  control  whether  the  file  can  be  read 
from,  written  to,  or  executed  by  either  the  owner  or  the  public 
(all  other  users.)  When  on,  these  six  attributes  function  as 

follows: 


Owner  read 
permission 

Owner  write 
permission 


Owner  execute 
permission 


Puldic  read 


Public  write 
^  permission 

Public  execute 
permission 


The  owner  can  read  from  the  file.  Use  this 
permission  to  prevent  binary  files  from 

being  used  as  text  files. 

The  owner  can  write  to  the  file  or  delete  it. 
Use  this  {iermisii&ii  to  p'oteet  iiixportant 
files     from     accidental    deletion  or 

modification. 

The  owner  can  load  the  file  into  memory 
and  execute  it.  To  be  loaded,  the  file  must 
contain  one  or  more  valid  OS-9  memory 
modules. 

Anyone  can  read  and  copy  the  file. 
Anyone  can  write  to  w  delete  ihe  file. 

Anyone  can  execute  the  file. 


Jbr  example,  if  a  file  has  all  permissions  on  except  write  permit 
to  public  and  read  permit  to  public,  the  owner  tos  unrestricted 
access  to  the  £Qe.  Other  users  can  execute  it  tat  caanst  r@ad, 
copy,  delete,  or  alter  it. 

Exmateing  m.€  Cliimging  File  Al^eSMm 

You  can  tise  the  EIR  command,  with  tlie  II  (entire)  ^tion,  to 

examine  the  security  permissions  of  all  files  in  a  particular 
directory.  An  example  of  output  using  DIR  E  on  the  current  data 
directory  is: 

Directory  of   .  1B;2fli44 

Owner  Last  ffl«iif  led  Ittriiaalet  S««ter  %t'eee«nt  Mm 


8G/07/31  1436 

86/87/31  1437 

86/07/31  1442 

86/«7/31  1419 


 r-wr 

d-ewrewr 
d-ewrewr 
 wr 


71 
1B8 
IBd 


6567  QSSBoot 
BGB  CMOS 
80  SYS 
55  startup 
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The  Attributes  column  shows  which  attributes  are  on  by  listing 
one  or  more  of  the  following  codes. 

dsewrewr 


' — >  public  read 

I — >  pablic  write 

I — >  public  ©EBcute 

' — >  single-user 

' — >  directory 
For  example,  the  first  file  shows: 

 r  -wr 

This  means  that  (1)  The  file  is  not  a  directory.  (2)  It  is  share- 
able. (3)  The  public  cannot  execute  it  or  (4)  write  to  it,  but  can 
(5)  read  it.  (6)  The  owner  cannot  execute  the  file,  but  can  (7) 
write  to  it,  and  (8)  can  read  it. 

To  examine  the  attributes  of  a  particular  file,  use  ATTR.  Typing 
ATTR  followed  by  a  filename  diows  you  the  file's  current  attri- 
butes, for  example: 

attr   f  ile2  |  ENTER  | 

A  possible  screen  display  is: 

 wr -wr 

To  change  a  file's  attributes  use  ATTR  and  a  filename,  followed 
by  a  list  of  one  or  more  attribute  abbreviations.  However,  you 
must  own  a  file  before  you  can  change  its  attributes. 


' — 3>  owner  write 


owner  read 


>  owner  execute 
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The  following  command  enables  public  write  and  public  read  per- 
missions and  removes  the  execute  permission  for  both  the  owner 
and  the  public: 

attr  file2  pw  pr  -e  -pe  | ENTER"! 

Note:  In  order  to  protect  data  stored  in  directories,  the  D 
attribute  behaves  somewhat  differently  from  the  other  attri- 
butes. You  cannot  use  ATTR  to  turn  on  the  D  attribute — 
only  MAKDIR  can  do  that — and  you  can  use  ATTR  to  turn 
off  D  only  if  the  directory  is  empty. 

Record  Lockout 

When  two  or  more  processes  use  the  same  file  simultaneously, 
they  might  attempt  to  update  the  file  at  the  same  time,  causing 
unpredictable  results.  When  you  open  a  file  in  the  update  mode, 
OS-9  eliminates  the  problem  of  simultaneous  use  by  locking  the 
sections  of  the  file.  The  lock  covers  any  disk  sectors  containing 
the  bytes  last  read  by  each  process  accessing  the  file.  If  one  pro- 
cess attempts  to  access  a  locked  portion  of  a  file,  OS-9  puts  the 
process  to  sleep  until  the  locked  area  is  free. 

OS-9  moves  the  lock  and  frees  the  area  when  it  reads  from  or 
writes  to  another  area.  The  system  removes  a  lock  on  a  file  when 
the  process  associated  with  the  lock  closes  its  path  to  the  file.  A 
process  can  have  only  one  lock  on  a  file,  but  it  can  have  locks  on 

more  than  one  file. 

You  can  lock  an  entire  file  by  activating  its  single  user  bit.  (See 
the  earlier  section  "Examining  and  Changing  File  Attributes.") 
When  the  single  user  bit  is  on,  only  one  proceSi  can  open  a  path 
to  the  file  at  a  time.  Attempts  by  other  proeessies  to  aeoess  the 
file  result  in  an  error. 
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Device  Names 

Each  physical  I/O  device  supported  by  OS-9  has  a  unique  name. 
The  following  list  describes  some  of  the  device  names  supported 
by  the  system,  ^ur  system  diskette  already  contEdns  several  of 
these  devices.  Yaa  can  define  others  to  use  with  CONFIG. 


D0_35S 

Floppy  Disk  Drive  /DO,  single  sided,  35 

cylinders. 

DL35S 

Floppy  Disk  Drive  /Dl,  single  sided,  35 

cylinders. 

mjsm 

Floppy  Disk  Drive  fD2,  single  sided,  35 

cylinders. 

D3_35S 

Floppy  Disk  Drive  /D3,  single  sided,  35 

cylinders. 

DDDQ_35S 

Defkult  Disk  Drive  /DO,  single  sided,  35 

cylinders. 

D0L.4OD 

Floppy  Disk  Drive  /DO,  double  sided,  40 

cylinders. 

D1_40D 

Floppy  Disk  Drive  /Dl,  double  sided,  40 

cylinders. 

D2_40D 

Floppy  Disk  Drive  /D2,  double  sided,  40 

cylinders. 

DDD0_40D 

Default  Disk  Drive  /DO,  double  sided,  40 

^Hndesrs. 

Di_80D 

Floppy  Disk  Drive  /Dl,  double  sided,  80 

cylinders. 

D2_80D 

Floppy  Disk  Drive  /D2,  double  sided,  80 

cylinders. 

P 

a  printer  using  the  KS'-lSf  serial  port 

TERM 

your  computer  keyboard  and  video  display 

Tl 

a  terminal  port  using  the  standard  RS-232 

port 

T2 

a  terminal  using  the  optional  RS-232 

communications  pak 

T3 

a  terminal  using  the  optional  RS'-232 

communications  pak 

Ml 

a  modem  using  an  optional  300  baud  modem 

pak 

m 

a  modem  using  an  optional  300  baud  imAsm 

pak 

W 

a  generic  window  descriptor 

Wl 

window  device  Number  1 
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W2  window  device  Number  2 

W3  window  device  Number  3 

W4  window  device  Number  4 

W5  window  device  Number  5 

W6  window  device  NuBaber  6 

W7  window  device  Number  7 


Although  OS-9  and  your  computer  can  access  all  these  devices, 
your  original  diskette  does  not  configure  it  to  do  so.  For  informa- 
tion on  configuring  your  system,  see  Chapter  7  of  Getting 
Started  With  OS-9. 

Because  device  names  are  at  the  root  of  the  file  system,  you  can 
use  them  only  as  the  first  part  of  a  pathlist.  Always  precede  the 
name  pf  a  device  with  a  sla!^. 

When  you  refer  to  a  non-disk  device,  for  example  a  terminal  or 
printer,  use  only  the  device  name.  /P,  for  instance,  is  the  full 
allowable  papist  fyr  a  ^nt^. 

Mote:  An  I/O  device  name  is  actually  the  name  of  an  OS-9 

device  descriptor  that  you  precede  with  a  slash  (/).  OS-9 
automatically  loads  device  descriptors  during  the  OS-9  boot 
sequence.  You  can  add  or  delete  other  device  descriptors 
while  the  system  is  running  or  add  device  descriptors  to  the 
bootfile  using  CONFIG. 
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Advanced  Features  of  the  Shell 


This  chapter  discusses  the  advanced  capabilities  of  the  shell.  In 
additioji  to  basic  command  line  processing,  the  shell  feicilitates: 

•  Input/output  redirection,  including  filters 

•  Memory  allocation 

•  Multitasking  (concurrent  execution) 

•  Procedure  file  execution 

•  Built-in  commands 

You  can  use  t^eie  advanced  capabilities  in  many  combisaations. 
Following  are  several  racamples.  Study  the  basic  rules,  use  your 
imagination,  and  explore. 

More  About  Command  Line  Processing 

The  shell  is  a  program  that  reads  and  processes  command  lines, 
one  at  a  time,  from  the  computer's  input  device  (usually  your 
keyboard).  It  parses  (scans)  each  line  to  idenfil^  and  profess  any 
of  the  following  parts  that  might  be  present: 

•  A  program,  procedure  file,  or  built-in  command 

•  Parameters  to  be  passed  to  the  program 

•  Execution  modifiers  to  be  processed  by  the  shell 

For  some  commands,  only  the  keyword  (the  program,  procedure 
file,  or  command  name)  must  be  present.  Other  commands  have 
required  or  optional  parameters.  As  well,  a  command  line  can 
include  modifiers  that  influence  the  operation  of  the  command. 
OS-9  features  that  affect  command  execution  are: 

Execution  Let  you  inereatse  the  amoaiit  of  random  access 
Modifiers       memory  (RAM)  available  for  a  command.  Also 

lets  you  redirect  input  to  a  process,  output  from 

a  process,  or  both. 

Command  Let  you  enter  more  than  one  command  on  a  line, 
Separators     perform  concurrent  execution  of  commands,  or 

connect  the  input  or  output  of  one  command  to 

another  comm^id. 
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Command  Lets  you  group  all  the  commands  that  you  want 
Grouping       affected  hy  command  modifiers  or  separators. 

Note:  The  next  section,  "Command  Modifiers,"  provides 
details  on  these  features. 

Once  the  shell  identifies  the  keyword,  it  processes  any  modifiers. 
It  then  assumes  the  remaining  text  consists  of  parameters, 
which  it  passes  to  the  program  being  called. 

When  the  shell  receives  a  built-in  command,  it  immediately  exe- 
cutes it.  If  it  receives  a  command  that  is  not  built  in,  it  searches 
for  the  appropriate  program  and  then  runs  it  as  a  new  process. 
The  kesnvord  must  be  the  first  entry  in  any  line. 

While  the  program  is  running,  the  shell  deactivates  itself.  At  the 
termination  of  the  program,  the  shell  reactivates  and  accepts  the 
next  input.  This  cycle  continues  until  the  shell  detects  an  end-of- 
file  in  the  input  path.  It  then  terminates  its  own  execution.  You 
can  input  mm.,  end  of  file  from  the  keyboard  by  prftsiinf 
imm'tmmi 

Following  is  a  sample  shell  command  line  that  calls  the 

assembler. 

In  this  example: 
I   ASM  is  the  beywcard. 


sourcefile,  1,  and  -o  are  the 
parameters  passed  to 
ASM. 

>/P  Is  a  modifier  that 
redirects  the  output  (the 
listing)  to  the  system's 
printer. 

#12k  is  a  modifier  that 
asks  the  system  to  assign 

12K  bytes  of  memory 
instead  of  a  smaller  default 
amount 


I 

asm  sourcefile  1   -o  >/p  #12;k 
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Command  Modifiers 

Add  commaaid  modifiers  to  a  command  line  to  change  the  way  in 
which  the  command  functions.  Modifiers  let  you  tailor  OS-9  com- 
mands to  your  specifications.  I^P®  them  in  a  command  line  after 
the  keyword  and  either  before  or  after  ottter  parameters  you 

might  be  using. 

The  shell  processes  command  modifiers  before  it  executes  a  pro- 
gram. If  it  detects  an  error  in  any  of  the  modifiers,  it  stops  exe- 
cution and  rep(Hi;s  the  error. 

The  shell  strips  command  modifiers  from  the  part(s)  of  the  com- 
mand line  passed  to  the  program  as  parameters.  Therefore,  you 
cannot  use  the  characters  reserved  as  modifiers  (#;!<>&) 
inside  other  parameters. 

Execution  Modifiers 

Execution  modifiers  alter  the  amount  of  memory  commzinds  have 
available,  or  they  redirect  command  input  or  output. 

Alternate  Memory  Size  Modifier.  When  the  shell  invokes  a 
command  program,  it  allocates  the  minimum  amount  of  working 
RAM  (random  access  memory)  specified  in  the  program's  module 

header. 

Note:  All  executable  programs  include  a  module  header 
which  holds  the  program's  name,  size,  memory  require- 
ments, and  other  information.  For  information  on  viewing 
the  contents  of  a  module  header,  see  the  IDENT  command. 

You  might  want  to  increase  a  command's  default  memory  size. 
Yaa.  can  assign  memory  either  in  256-l3yte  pages  or  in  1024-byte 
increments.  To  add  memory  in  pages,  use  the  modifier  #n,  where 
n  is  the  number  of  pages.  To  add  memory  in  1024-byte  incre- 
ments, use  the  modifier  #reK,  where  n  is  the  number  of  1024- 
byte  increments. 

The  following  two  examples  have  identical  results: 

copy  #8  filel  file2  |  ENTER  |  (8x256  =  2048  bytes) 
copy  #2K  filel  fUeg  |ENT£fl|      (2  X  1024  =  2048  l^tes) 
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I/O  Redirection  Modifiers.  Input/output  redirection  modifiers 
reroute  a  program's  I/O  from  the  standard  path  to  alternate  files 
or  devices. 

One  of  OS-9's  advantages  is  that  its  programs  use  standard  I/O 
paths  rather  than  individual,  specific  file,  or  device  names.  You 
max  eisily  redtjriet  the  FO  to  say  file  m  le^rffee  witlamt  alterii^ 
the  program  itself. 

Programs  that  normally  receive  input  from  a  terminal  or  send 
output  to  a  terminal  use  one  or  more  of  these  three  standard  I/O 
paths: 

•  Standard  mpat  path — Routes  data  from  the  terminal's 
keyboard  to  programs.  The  standard  input  path  is  Path 
Number  0. 

t&e  the  lessrthan  symbol  (<)  to  redirect  data  to  this 
path. 

•  Standard  output  path — Routes  data  from  programs  to 
the  terminal's  display.  The  standard  output  path  is  Path 
Number  1. 

Use  the  greater-than  symbol  (>)  to  redirect  data  from 

this  path. 

•  Standard  error  output  path — ^Routes  routine  status 
messages  (prompts  and  errors)  to  the  terminal's  display. 

(The  name  error  output  path  is  somewhat  misleading, 
since  many  kinds  of  messages  in  addition  to  error  mes- 
sages feravdi  %m  path.)  The  standard  rarer  path  is  Path 

Use  two  greater-than  symbols  (>>)  to  redirect  data 

from  this  path. 

When  you  use  a  redirection  modifier  in  a  command  line,  follow  it 
immediately  with  a  pathlist  for  the  substitute  device.  Pbr  exam- 
ple, you  can  use  LIST  to  redirect  the  contents  of  a  file  called 
Ooi^e^ondence  from  the  t@Wiiial  to  the  printer,  bf  ^in^ 

list  correspondence  »/p)  lENTERl 

The  shell  automatically  crmtfis^  Ofpens,  and  closes  files  referenced 
by  redirectioQ  modifiers  ai  i%^dM<  'Wm  system  immediately 
restores  nonnsi  JIQ  yaXhB  at  ibe  ecmsletiEin  of  any  com- 
mand using  redirection  modifiers. 
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In  the  next  example,  the  shell  redirects  DIR's  output — a  list  of 
files  in  the  MEMOS  direetory— to  the  file  /Dl/Savelisting: 

dir  /d0/memo5  >7d1 /BaveHBtinq  I  ENTER  | 

Yaa  can  now  view  the  ecoitents  of  Ssvelisting  by  typing: 

list   /dl/savellstlnc)  |ENTER| 

OS-9  displays  the  file  contents  in  a  format  similar  to  a  directory 
listing. 

Directory  of  /d0/memo5 
CMDS  SYS  startup 

DS9Boot 

You  can  use  one  or  more  redirection  modifiers  before  the  pro- 
gram's parameters,  after  the  program's  parameters,  or  both. 
However,  use  each  modifier  only  once  in  a  command. 

The  following  example  shows  how  you  can  use  all  of  the  redirec- 
tion modifiers  together  to  start  BASIC09  on  a  device  window  and 
redirect  all  input  and  output  to  it: 

ba5ic09  <>>>/w1  |  ENTER  | 

When  you  redirect  multiple  paths,  you  must  use  the  redirection 
symbols  in  the  proper  order  as  shown  here: 

Legal  niegal 

<>  /wl  ><  /wl 

<»  /wl  »<  /wl 
>»  /wl       »<  /wl 

Command  Separators.  You  can  include  more  than  one  com- 
mand on  a  command  line  by  using  command  separators.  Com- 
mand separators  cause  multiple  commands  to  execute  either 
sequentially  or  concurrently,  depeaiding  on  the  separator  you 
use. 

Sequential  execution  means  that  one  program  must  complete  its 
function  and  terminate  before  the  shell  lets  the  next  program 
execute.  Concurrent  execution  means  that  two  or  more  programs 
begin  execution  and  run  simultaneously. 
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Sequential  Execution  Using  the  Semicolon.  Using  a  semi- 
colon between  commands  on  one  line  causes  them  to  execute 
sequentially.  For  instance: 

copy  myfile  /d1 /newf  i  1  e  ;   dir  >  /  p  |  ENTER] 

This  command  causes  the  shell  to:  (1)  esBcute  the  COPY  com- 
mand, (2)  enter  a  waMng  S^te  until  (^Wf  tsKminates,  then 
avmke,  and  (3)  esecute  DIR. 

If  an  error  occurs  in  any  program,  the  shell  does  not  execute 
subsequent  commands,  regardless  of  the  state  of  the  SHELL 
command's  X  (stop  on  error)  opticm. 

Here  are  two  more  samples  of  commands  using  the  semicolon: 

copy  oldfile  newflle;   del   oldflle;    list  newfile 

iimi 

dir  /dl /myfile;   list   temp  >/p;   del   t  emp  I  ENTER  | 

Commands  separated  semicolons  are  in  fact  separate  and 
equal  child  processes  of  the  shell. 

Note:  When  one  process  creates  another  process,  OS-9  calls 

the  creator  the  parent  process  and  the  created  process  the 
child  process.  The  child  can  become  a  parent  by  creating 
yet  another  process. 

Concurrent  Execution  Using  the  Ampersand.  You  can  use 

the  ampersand  (M  to  cause  multiple  commaais  to  run  at  the 
same  time.  Each  command  you  specify  runs  as  a  separate  child 
process  of  the  shell.  That  is,  for  each  process,  the  shell  creates  a 
separate  shell  to  handle  the  operation.  When  the  process  is  com- 
plete, the  child  shell  terminates,  or  dies. 

While  more  than  one  process  is  running,  OS-9  divides  execution 
time  equally  among  the  processes. 

The  number  of  pro-ams  that  can  run  at  the  same  time  varies. 
It  depends  on  the  amount  of  free  memory  in  the  system  and  the 
memory  requirements  of  the  programs  being  executed. 

An  example  of  a  simple  command  line  using  the  &  separator  is: 

dir  >/p&  I  ENTER  I 
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The  shell  begins  to  run  DIR,  sending  output  to  the  printer.  At 
the  same  time  it  displays  both  the  number  of  the  forked  process 
(DIR)  and  a  new  prompt,  like  this: 

DS9: 

To  fork  a  process  means  to  create  a  process  as  a  branch  of 
another  process — a  subroutine. 

After  using  the  ampersand  to  fork  a  background  process,  you 
can  then  enter  another  cammand,  which  the  shell  executes  wliile 
dtttput  frtm  your  original  command  continues  to  go  to  the 
printer.  This  means  you  don't  waste  time  waiting  for  OS-9  to  fin- 
ish a  task.  At  times,  the  keyboard  might  not  seem  to  respond  to 
your  typing,  because  characters  do  not  appear  on  the  screen. 
However,  OS-9  stores  the  characters  in  the  keyboard  buffer  and 
displays  th«i  as  soon  as  the  shell  cam  accept  input  again. 

If  you  lam%  several  precedes  ruiimiig  simoltdaeoasfy  and  wamt 
information  about  them,  use  the  FROGS  command. 

Combiniz^  Sequential  and  Concurrent  Executions.  %u  can, 
if  you  want,  use  both  the  concurrent  and  sequential  command 
separators  in  one  command  line.  For  example: 

dir  >/p&  list  filel4  copy  filel  file2;  del  temp 
rENTERl 

Because  the  &  modifier  joins  the  DIR,  LIST,  and  COPY  com- 
mands, these  commands  run  concurrently.  But,  because  a  semi- 
colon precedes  ^  DIL  ^mnand,  DEL  does  not  rttn  until  the 
other  commands  terminate. 

Using  Pipes:  The  Exclamation  Mark.  %u  can  use  the  excla- 
mation mark  (!)  to  construct  pipelines  for  OS-9  commands.  Pipe- 
lines consist  of  two  or  more  concurrently  executing  programs 
with  standard  input  paths,  and  standard  output  paldis  or  both, 

connected  to  each  other  with  pipes. 

Pipes  are  the  primary  means  of  transferring  data  from  process 
to  process^  me  vital  to  iatis^oeess  ci^asciui^cations.  Pipes 
are  first-in,  first-out  buffers,  or  holding  areas  for  data. 


8-7 


OS -9  Commands  Reference 


The  shell  automatically  buffers  and  synchronizes  I/O  transfers 
using  pipes.  A  single  pipe  can  direct  data  to  several  destinations 
or  readers,  and  can  receive  data  from  several  sources,  or  writers 
on  a  first-come,  first-serve  basis.  An  end-of-file  occurs  if  a  pro- 
gram attempts  to  read  from  a  pipe  when  writers  are  not  avail- 
able to  send  data.  Conversely,  a  write  error  occurs  if  a  program 
attempts  to  write  to  a  pipe  when  readers  are  not  available. 

Pipelines  af*  dSMted  l^jf  tie  shell  when  it  processei  aa  iSiput  line 
with  one  or  more  pipe  separators  (!).  For  each  pipe  separator,  the 
shell  directs  the  standard  output  of  the  program  on  the  left  of 
the  pipe  separator  to  the  standard  input  of  the  program  on  the 
right  of  the  separator.  The  shell  creates  an  individual  pipe  for 
each  f  ^pe  Mpamtor  in  the  command  line.  Pbr  example: 

update  <mastef  file   !   sort   I  write  report 

>/p  I  ENTER  I 

This  command  redirects  input  from  a  path  called  Master_file  to 
a  file  named  Update.  The  output  of  Update  becomes  the  input  for 
the  program  Sort.  The  output  of  Sort,  in  turn,  becomes  the  input 
for  the  program  Write_report.  Finally,  the  command  redirects 
output  from  Write_report  to  the  printer.  The  shell  esecutes  all 
programs  in  a  pipeline  concurrently.  The  pipes  synchronize  the 
programs  so  the  output  of  one  never  gets  ahead  of  the  input 
request  of  the  next  program.  This  synchronization  means  that 
data  cannot  flow  through  a  pipeline  any  faster  than  the  slowest 
program  can  process  it. 

Raw  Disk  Input/Output.  OS-9  has  a  special  pathlist  function 
to  perform  raw  physical  input/output  operations  on  a  disk.  The 
pathlist  consists  of  the  device  name,  immediately  followed  by  the 

"@"  character. 

This  command  causes  OS-9  to  treat  the  entire  diskette  in  Drive 
/DO  as  one  logical  file.  The  operation  reads  each  byte  of  each  sec- 
tor, without  regard  to  actual  file  structure.  Commands  such  as 
DIR,  ATTR,  and  MFREE  use  this  feature  to  access  sectors  of 
disks  that  are  not  part  of  file  data  areas,  such  as  header  sectors. 

Warning:  When  using  this  raw  access,  use  extreme  cau- 
tion. Because  you  can  write  on  any  sector,  you  can  easily 
damage  file  or  directory  structures  and  lose  data.  Using  @ 
defeats  any  file  security  and  record  locking  systems. 
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To  convert  a  byte  address  to  a  logical  sector  number  when  using 
@,  multiply  the  sector  number  by  256.  Conversely,  the  logical 
sector  number  of  a  byte  address  is  the  byte  address,  modulo  256. 

Command  Grouping 

"Sou  can  enclose  sections  of  command  lines  in  parentheses  to  per- 
mit modifiers  and  separatoTS  to  affect  an  entire  set  of  programs. 
The  shell  processes  the  material  in  the  parentheses  by  recur- 
sively calling  itself  to  execute  the  enclosed  command  list. 

For  example,  if  you  want  to  send  directory  listings  of  the  ROOT 
directory  of  Drive  /DO  and  then  the  ROOT  directory  of  Drive  fDl 
to  the  printer,  you  can  type  either: 

dir  /d0   >/p;   dir  /d1   »/p  |  ENTEfl  | 

or; 

(dir   /d0;    dir   /d1)   >/p  |  ENTER) 

The  results  are  identical  except  that  the  system  keeps  the  printer 
continuously  in  the  second  example.  In  the  first  example,  another 
user  could  steal  the  printer  between  DIR  commands. 

You  can  group  commands  to  cause  programs  to  execute  both 
sequentially  and  concurrently  with  respect  to  the  shell  that  ini- 
tiated them.  Ebr  instance: 

(del  file1;   del  file2;  del  f ile3)&  (IntoI 

Here,  the  shell  does  the  overall  deleting  process  concurrently 
with  whatever  else  you  tell  it  to  do,  because  you're  using  &. 
However,  the  shell  deletes  the  three  specified  files  sequentially 
because  you're  using  semicolons  within  the  parentheses. 

Suppose  you  have  a  program  named  Makeuppercase  that  con- 
verts lowercase  characters  to  uppercase  and  a  program  named 
Transmit  that  sends  data  to  another  cMputw,  you  can  use  a 
cominand  lixm  like  this; 

(dir  emda ;  dir  sys )  !  makeuppercase  !  transmit 
[ ENTER  I 

The  shell  processes  the  output  of  the  first  DIR  command  and 
then  the  second.  It  sends  all  the  DIR  output  to  Makeuppercase, 
and  Transmit  sends  all  the  output  to  another  computer. 
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Shell  Procedure  Files 

The  shell  is  a  re-entrant  program  .  This  means  it  can  be  simulta- 
neously executed  by  more  than  one  process.  Like  most  other  OS- 

9  programs,  the  shell  uses  standard  I/O  paths  for  routine  input 
and  output. 

OS-9's  shell  offers  you  a  special  feature,  a  time  and  effort  saver 
called  a  procedure  file.  A  procedure  file  is  a  related  group  of 
commands,  and  when  you  run.  the  file,  you  execute  all  the 

commands. 

Other  names  for  procedure  file  processing  £ire  batch  and  back- 
ground  p^ieessiMg.  A  procedure  file  becomes  new  input  for  the 

shell.  By  running  a  procedure  file,  you're  using  the  shell  to  cre- 
ate a  new  shell,  a  subshell  that  accepts  and  carries  out  the  com- 
mands in  the  pjoeedtire  file. 

Note:  If  you  plan  to  use  the  same  command  sequences 
repeatedly,  create  a  procedure  file  to  do  the  job  by  using 

When  jm  enter  atty  comniaHd  lilie,  the  shell  looks  i3r  the  speci- 
fied program  in  memory  or  in  the  execution  directory.  If  it  can- 
not find  the  program  there,  it  searches  the  data  directory  for  a 
file  with  the  specified  nmsfm.  If  it  finds  the  file,  the  shell  auto- 
matically interprets  it  as  a  ptrocedure  file,  and  creates  the  sub- 
shell,  which  executes  the  conunands  listed  in  the  procedure  file. 

Procedure  files  can  also  let  the  ccnnputer  ejcecute  a  lengthy 
series  of  programs  while  it  is  unattended,  or  even  while  it  is  run- 
ning other  programs. 

There  are  two  ways  to  run  a  procedure  file.  For  instance,  to  exe- 
cute a  procedure  file  called  Mailsequence,  type  either: 

shell  mal  laequence  fENTER  | 

or 

ma  i  1  sequence  |  ENTER  | 

Both  commands  do  the  same  thing:  create  a  subshell  to  run  the 
commands  you've  built  into  your  Mailsequence  procedure  file. 

10  run  a  procedure  file  in  a  concuxrent  mode,  use  the  arnpersand 
^1  ioadiler.  im  hmg  m  msmst^  is  ««aiiiLl>i%  f  cm  mm  ran  any 
number  of  files  concurrmtly. 
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You  can  even  build  procedure  files  to  sequentially  or  concurrently 
execute  other  procedttre  files. 

Note:  If  you  use  procedure  fOes  to  run  programs  you  don't 
intend  to  monitor  closely,  you  can  redirect  standard  output 
and  standard  error  output  to  another  file.  Later  you  can 
review  the  file's  contents.  Output  redirection  eliminates  the 
annoying  output  of  shell  messages  on  your  terminal  at  ran- 
dom times. 


BuJUt-in  Shell  CQixuaistzi^  and  Optioni 

The  shell  has  a  number  of  built-in  commands  and  options. 
Whenever  you  use  one  of  these  functions,  the  shell  executes  it 
without  loading  it  or  creating  a  new  process  to  execute  it. 

You  can  execute  built-in  functions  alone,  use  them  at  the  begin- 
ning of  a  command  line,  or  us©  them  following  any  program  sep- 
arator. Yaa  can  separate  adjafflsot  huilt-inE  eomnmods  by  spaces 

The  built-in  commands  and  their  functions  are: 


CHD  patbHst 


CHX  pathlist 


EX  modmmne 


i-devname 


Changes  the  data  directory  to  the  directory 

specified  by  the  pathlist. 

Changes  the  execution  directory  to  the  direc- 
tory specified  by  the  pathlist. 

Directly  executes  the  module  Jiamed.  This 
function  deletes  the  shell  pf  ose^  gp  that  it 
ceases  to  exist  and  executes  the  new  miodcde  fn 
its  place.  Use  EX  to  replace  the  executing 
shell  with  the  program  specified  by  modnarm. 
Ysa.  can  also  use  EX  without  a  module  name 
to  eliminate  the  current  shell,  for  example,  a 
shell  you  initialized  in  a  window  (see  below). 

Makes  a  shell  an  immortal  shell.  This  means 
that  when  the  shell  ends,  due  to  an  EOF,  OS-9 
restarts  it.  Each  time  the  shell  restarts,  it  has 
the  same  data  and  execution  directories.  To 
kill  an  immortal  shell,  use  EX  to  "chain"  to  a 
null  process,  such  as: 


ex  ENTER 
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w  Waits  for  any  process  to  terminate. 

*  text  Allows  you  to  make  a  comment.  The  shell  6om 

not  process  text  following  the  asterisk.  Vm 
this  function  to  label  operations  in  a  p-ocedure 

file. 

kill  procID         Stops  the  specified  process. 

setpr  procID  Changes  the  specified  process's  priority 
aiunber  number. 

X  Caiises  the  ihell  to  cease  operation  whenever 

an  OTTor  occurs  (a  system  defeiult). 

-x  Causes  the  shell  to  continue  operation  when 

an  error  occurs.  Use  this  function  in  procedure 
files  to  enable  the  shell  to  continue  to  other 
commands  if  one  command  process  fails 

be«%tiie  <tf  a  ifstw  mm. 

p  Turns  the  shdl  p'mpt  and  messages  ctn  (a 

system  Mtult). 

-p  Inhibits  the  shell  prompt  and  messages.  Use 

this  option  in  procedure  files  to  disable  screen 
display.  Be  sure  to  turn  the  prompt  and  mes- 
sage function  back  on  afterward. 

t  Makes  the  shell  copy  all  input  lines  to  output. 

Use  this  function  with,  a  ppoeedure  file  to 
cause  command  lines  to  display  as  they 

execute. 

-t  Sets  the  system  so  that  it  does  not  copy  input 

lines  to  output  (a  system  de&ult). 

Running  Compiled  Intermediate 

Code  Programs 

Before  the  shell  executes  a  program,  it  checks  the  program  mod- 
ule's langliaip  If  it  ii  Wt  6809  machine  language,  the  shell 
calls  the  appropriate  run-time  system  for  that  module. 
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For  instance,  if  you  have  BASIC  09  on  your  OS-9  system  and 
want  to  run  a  BASIC09  I-code  module  called  Adventure,  you  can 
type: 

baalc09  adventure  |  ENTER  | 

or: 

adventure  |  ENTER  | 

or: 

runb  adventure  |  ENTER  | 

In  the  last  example,  the  shell  uses  the  RUNB  module  to  inter- 
pret the  Adventure  I-code  module. 
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Chapter  4 


Multiprogramming  and 
Memory  Management 


One  of  OS-9's  most  valuable  capabilities  is  multiprogramming — 
sometimes  called  timesharing  or  multitasking.  This  feature  lets 
your  computer  run  more  than  one  process  at  the  same  time. 
Multiprogramming  can  be  a  time  saving  advantage  in  many  sit- 
uations. For  example,  jnau  earn,  ©iit  one  program  while  the  system 
prints  another.  Or  you  can  use  your  Color  Computer  to  control  a 
househoilid  alasem.  system,  lighting,  and  Ifeaidng  emd  at  the  same 
time  use  it  fer  routine  work  or  entertainment. 

OS-9  uses  multiprogramming  regularly  for  internal  functions. 
You  can  use  it  by  putting  an  ampersand  at  the  end  of  a  com- 
mand line.  Doing  this  causes  the  shell  to  run  jraur  command  as 
a  background,  or  concurrent,  task. 

To  run  several  processes  simultaneously,  OS-9  must  coordinate 
its  input/output  system  and  CPU  time  and  allocate  its  memory 
as  needed.  This  chapter  gives  you  some  basic  information  about 
how  OS-9  manages  its  resources  to  optimize  system  efficiency 
and  make  efficient  multippogi^inuniiig  a  reali^. 

Processor  Time  Allocation 
and  Timeslicing 

CPU  time  is  the  most  predous  resource  ctf  a  i^nputer.  If  the 
CPU  is  busy  with  one  task  it  cannot  perform  another.  Bar  exam- 
ple, many  processes  must  wait  for  you  to  enter  information  from 
the  terminal.  While  the  process  is  waiting,  your  computer's  CPU 
must  also  wait.  "Sour  computer  is  limited  by  yoar  typing  speed. 

On  many  systems  tiiere  is  no  way  around  such  a  bottle  neck. 
However,  OS-9  is  more  efficient.  It  assigns  CPU  time  to  pro- 
cesses only  as  they  need  it. 

Tb  do  this,  GBrB  uses  timeslicing.  Timeslicing,  as  descaribed  in 
the  following  para,graphs,  lets  all  active  processes  share  CPU 

time. 

A  real-time  clock  interrupts  the  Color  Computer's  CPU  60  times 
each  second.  The  interruption  points  are  called  ticks,  and  the 
spaces  between  ticks  are  called  timeslices. 
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OS-9  allocates  timeslices  to  each  process.  At  any  tick  it  can  sus- 
pend execution  of  one  process  and  begin  execution  of  another. 
This  starting  and  stopping  of  processes  does  not  affect  their 
execution. 

How  often  OS-9  gives  a  process  timeslices  depends  on  the  pro- 
cess's priority  relative  to  the  priority  of  oStmt  miim  processes. 
You  can  access  priority  using  a  decimal  number  from  0  through 
255,  where  255  is  the  highest  priority. 

OS-9  automatically  gives  the  shell  a  priority  of  128.  Because 
child  processes  inherit  their  parents'  priorities,  the  shell's  child 
processes  also  have  priorities  of  128.  ^u  can  fmd  a  process's 
priority  wift  the  PBOGS  eominand,  and  em.  change  it  using  the 
SETPR  command. 

You  cannot  compute  the  exact  percentage  of  CPU  time  assigned 
to  any  particular  process,  because  there  are  some  dynamic  vari- 
ables involved,  such  m  &e  time  the  process  spends  waiting  for 
I/O  devices.  But  you  can  approximate  the  percentage  by  dividing 
the  process's  priority  by  the  sum  of  the  priority  of  all  acMve 
processes: 

process's  CPU  share  =  priority  of  the  process 

sum  of  the  priorities 
of  all  active  processes. 

Note:  Timeslicing  happens  so  quickly  that  it  looks  as  if  all 
processes  execute  simultaneously  and  continuously.  If,  how- 
ever, the  computer  becomes  overloaded  with  processing,  you 
might  notice  a  del£^  in  response  to  input  from  the 
nal.  Or,  you  might  notice  that  a  procedure  program  takes 
longer  than  usual  to  run. 

Process  States 

The  CPU  time  allocation  system  automatically  assigns  each  pro- 
cess one  of  three  states  that  describes  its  current  status.  Process 
states  are  important  fbr  coordinating  procd^  i^ieieulisn.  A 
cess  can  have  only  one  state  at  any  instant,  although  state 
changes  can  be  frequent.  The  states  are: 

•  Active — Applies  to  processes  currently  able  to  work — 
that  is,  those  not  waiting  for  input  or  for  anything  else. 
These  are  the  only  processes  assigned  CPU  time. 
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•  Waiting — Applies  to  processes  that  the  system  suspends 
until  tedtha*  pK)eess  tewftiftates.  This  state  allows  <«df- 
dination  of  sequential  process  execution.  The  shell,  for 
example,  is  in  the  waiting  state  during  the  execution  of  a 
command  it  has  initiated. 

•  Sleeping — Applies  to  a  process  suspending  itself  for  a 
specified  time,  or  until  receipt  of  a  signal.  (Signals  are 
inteinal  messages  that  coordinate  concurrent  processes.) 
This  is  the  typical  state  of  processes  waiting  for  input/ 

output  operations. 

The  shell  does  not  assign  CPU  time  to  sleeping  or  wait- 
ing processes.  It  waits  until  they  become  active.  The 
PROCS  command  gives  information  about  process  states. 

Creation  of  Proceises 

If  a  parent  process  creates  more  than  one  child  process,  the  chil- 
dren are  called  siblings  with  respect  to  each  other.  If  you  exam- 
ine the  parent/child  relationship  of  all  processes  in  the  system,  a 
hierarchical  lineage  becomes  evident.  In  fact,  this  hierarchy 
resembles  a  family  tree.  (The  family  concept  makes  it  easy  to 
describe  relationships  between  processes.)  OS-9  literature  uses 
the  family  concept  extensively  in  describing  OS-9's  multipro- 
gramming functions.) 

OS-9's  fork  function  automatically  performs  the  sequence  of  oper- 
ations required  to  create  a  new  process  and  initially  allocate 
resources  to  it. 

If  for  any  reason,  fork  cannot  perform  any  part  of  the  sequence, 
the  system  stops  and  fork  sends  its  parent  an  error  code.  The 
most  frequent  reason  for  failure  is  the  unavailability  of  required 
resources  (especially  memory),  or  the  inability  of  the  system  to 
find  the  specified  jaregrffin. 

A  p«eess  can  create  many  processes,  suli^ect  ottly  to  the  sraila- 
bility  of  unassigned  memory.  When  the  parent  issues  a  fork 
request  to  OS-9,  it  must  specify  certain  information: 

•  A  primary  module — The  name  of  the  program  to  be 
executed  by  the  new  process.  The  program  can  already 
be  present  in  memory,  or  OS-9  can  load  it  from  a  disk 
file  with  the  same  name. 
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•  Parameters — ^Data  to  be  passed  to  and  used  by  the  new 
process.  C^*^  copte  fefe  data  to  part  of  the  child  pro- 
cess's memory  area.  (Parameters  frequently  pass  file- 
names, initialization  values,  and  other  information.) 

The  new  process  inherits  some  of  its  parent's  properties, 
including: 

•  A  user  number — For  use  by  the  file  security  system  to 
identify  all  processes  belonging  to  a  specific  user.  (This 
is  not  the  same  as  the  process  ID,  which  ideaMflfes  a  pro- 
cess.) OS-9  obtains  this  number  from  the  system  pass- 
word file  when  a  user  logs  on.  The  system  manager  is 
always  User  0. 

•  Standard  input  and  output  paths — The  three  paths: 
input,  output,  and  error,  used  for  routine  input  and  out- 
put. Most  paths  can  be  shared  simultaiieousl||t  two  or 
more  processes. 

•  Ciirrent  directories— The  data  directory  and  the  eseeu- 

tion  directory. 

•  Process  priority. 

As  part  of  the  fork  operation,  OS-9  automatically  assigns: 

•  A  process  ID,  a  number  in  the  range  1  to  255  that  iden- 
tifies the  process.  Each  process  has  a  unique  number. 

•  Enough  memory  to  support  the  new  process.  In  OS-9,  all 
processes  share  a  memory  address.  OS-9  allocates  a  data 
area  for  the  process's  parameters  and  variables  and  a 

stack  for  each  process's  use.  It  needs  a  second  memory 
area  in  which  to  load  the  process  if  it  does  not  reside  in 
memory. 
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In  summary,  each  new  process  has: 

•  A  primary  module 

•  Parameters 

•  A  user  number 

•  Standard  I/O  paths 

•  Current  directories 

•  A  priority 

•  An  ID  number 

•  Memory 

Basic  Memory  Management  Functions 

Memory  management  is  an  important  OS-9  function.  OS-9  auto- 
matically allocates  all  system  memory  to  itself  and  to  processes, 
and  also  keeps  track  of  the  logical  contents  of  memory  (the  pro- 
gf&ta  fttodufes  that  are  resident  in  nlemory  at  any  given  time). 
The  result  is  that  you  seldom  need  to  bother  with  the  actual 
memory  addresses  of  programs  or  data. 

The  operating  system  and  each  process  have  individual  address 
spaces.  Each  address  space  has  the  potential  to  contain  up  to  64 
kilobytes  of  RAM  memory.  Using  memory  management  unit 
(MMU)  hardware,  OS-9  moves  memory  into  and  out  of  each 
address  space  as  required  for  system  operations. 

Although  each  unit  is  subject  to  the  64K  maximum  program 
size,  you  can  run  several  processes  simultaneously  and  utilize 
more  than  64K  overall.  The  system  logically  assigns  RAM  iMtt- 
ory  in  256-byte  pages,  but  the  MMU's  hardware  block  sfcf  li 
8K.  Each  of  these  physical  blocks  has  an  extended  address  that 
is  called  a  block  number.  For  example,  the  8K  physical  block 
residing  at  address  $3C000  to  $3DFFF  is  Block  Number  $3C. 

Within  an  address  space,  OS-9  assigns  memory  from  higher 
ailfeft&SS  (downward  for  program  modules  and  from  lower 
addresses  upvmrd  for  data  areas.  The  following  chart  shows  this 
organization: 
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program  modules 
(RAM  or  ROM) 


highest  address 


unused  space 
(RAM  or  empty) 


lowest  address 


Loading  Program  Modules  into  Memory 

When  performing  a  fork  operation,  OS-9  first  attempts  to  locate 
the  requested  program  modttle  by  searching  the  module  direc- 
tory, which  has  the  address  of  every  module  present  in  memory. 
The  6809  instruction  set  supports  a  type  of  program  called  re- 
entrant code,  which  means  that  processes  can  share  the  code  of  a 
program  simultaneously. 

Since  almost  all  OS-9  family  software  is  re-entrant,  the  system 
cart  make  Ihe  most  efficient  xtse  of  memory,  ftr  example,  suppose 
that  OS-9  receives  a  request  (from  a  process)  to  run  BASIC09 
(which  requires  22  kilobytes  of  memory),  but  has  already  loaded 
it  into  memory  for  another  process.  Because  the  software  is  re- 
entrant, OS-9  does  not  have  to  load  it  again  and  use  another 
22K  of  memory.  Instead  the  new  process  shares  the  original 
BASIC09  by  including  the  location  of  the  BASIC09  module  in  its 
memory  map. 

OS-9  automatically  keeps  track  of  how  many  processes  are  using 
each  progr£mi  module,  and  deletes  the  modiQe  ^en  all  processes 
using  it  terminate. 

If  iSm  requested  program  does  not  yet  reside  in  memory,  OS-9 
uses  mam  as  a  pathlist  t&lmmam}  and  attempts  to  Ic^  the 
program  from  disk. 
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Every  program  module  has  a  module  header  describing  the  pro- 
gram and  its  memory  requirements.  OS-9  uses  the  header  to 
determine  how  much  m^oaory  the  process  needs  fitr  variable  star>t 
age.  The  modxde  hi^rfbr  includes  other  inJformatfen  ateit  lis  laso- 
gram,  and  is  an  essential  part  of  the  OS-9  machine  language 
operation. 

You  can  also  place  commands  or  programs  into  memory  using 
the  LOAD  command.  Doing  so  makes  the  program  available  to 
OS-9  at  any  time,  without  having  to  be  loaded  from  disk.  A  pro- 
gram is  physically  loaded  into  memory  only  if  it  does  not  already 
reside  there. 

LOAD  causes  OS-9  to  copy  the  requested  module  from  a  file  into 
memory,  verifying  the  CRC  (Cyclic  Redundancy  Check).  If  the 
module  is  not  already  in  the  modtile  directctry,  OS-9  adds  it. 

If  the  program  module  is  already  in  memory,  the  load  process 
still  begins  in  the  same  way.  But,  when  OS-9  attempts  to  add 
the  module  to  the  module  directory  and  notices  that  the  module 
is  already  there,  it  merely  increments  the  known  module's  link 
count  (the  number  of  processes  using  the  module). 

When  OS-9  loads  multiple  modules  in  a  single  file,  it  associates 
th^  lo^cally  lift  the  ffiemea^  mamgieaugat  system.  TSm  cannot 
deallocate  any  of  the  group  modules  until  all  modules  have  zero 
link  counts.  Similarly,  linking  to  one  module  within  a  group 
causes  all  other  modules  in  the  group  to  be  mapped  into  the  pro- 
cess's address  space. 

Deleting  Modules  From  Memory 

tWLINK  is  the  opposite  of  LOAD.  It  decreases  a  program  mod- 
ule's link  count  by  one.  When  the  count  becomes  zero  (prestun- 
vag  that  the  module  Is  iid  longap  ttied  by  amf  pf^eesa),  OS-9 
deletes  the  module,  deallocates  its  memory,  and  removes  its 

name  from  the  module  directory. 

Warning:  Never  use  the  UNLINK  command  on  a  program 
or  a  module  not  previously  installed  using  LOAD.  Unlink- 
ing a  module  you  did  not  LOAD  (or  LINK)  might  perma- 
tientlf  iMete  It  vtet  the  pogram  Ismiiiales.  Hie  ihdl 
automatically  unlinks  programs  loaded  by  fork. 
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Suppose  you  plan  to  use  the  COPY  command  ten  times  in  a  row. 
Normally,  the  shell  must  load  COPY  each  time  you  the 
conuoand.  But  if  you  load  the  COPY  module  into  iSi&mXf  and 
then  enter  your  string  of  commands,  you  don't  have  to  wait  for 
the  system  to  load  and  unload  COPY  repeatedly.  When  you  fin- 
ish using  COPY,  use  UNLINK  to  unlock  the  module  from  mem- 
ory. The  seqxi^@  boks  like  this: 

1  o  a  d  c  o  py  I  WffiW\ 

copy  filel    f  ile1a  fENTERl 

copy  file2  f  i  le2a  (INTERI 

copy  file3   f  i  le3a  |  ENTER  | 

copy  file4   f  ile4a  |  ENTER  | 

eopy  fllef  f  ileSa  [enter] 

copy  filee  f  ileSa  [INTER  | 

copy  file?   f  i  1  e  7  a  [ENTER] 

copy  fileB  f  i  leSa  [ENTER  | 

copy  file9  f  ile9a  [ENTER] 

copy  f  iletg  f  lle10a  fENTERl 
unlink  copy  flNTlRl 

It  is  important  to  use  UNLINK  when  you  no  longer  need  the 
program.  Otherwise,  the  program  continues  to  occupy  memory 
that  might  be  used  for  other  purposes. 

Warning:  Be  careful  not  to  unlink  modules  that  are  in  use, 
because  OS-9  deallocates  the  memory  used  by  the  module 
and  imlseoys  its  contents.  All  programs  ustag  the  unlinked 
module  crash. 

Loadixm;  Multt|>l!e  Programs 

Becaiise  all  08-9  program  modttleis  are  posMm-independent,  you 
can  have  more  than  one  program  in  memory  at  the  same  time. 
Since  position-independent  code  (PIC)  programs  don't  have  to  be 
loaded  into  specific,  predetermined  memory  addresses  to  work 
correctly,  you  can  load  them  at  different  memory  addresses  at 
dififerait  $Mm. 

PIC  programs  require  special  types  of  machine  language 

instructions  that  few  computers  have.  The  ability  of  the  6809 
microprocessor  to  use  PIC  programs  is  a  powerful  feature  and 
one  of  the  greatest  aids  toward  multiprogramming.  You  can  load 
any  number  of  program  modules  until  available  system  memory 
is  full. 
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OS-9  automatically  loads  each  program  module  at  non-overlap- 
ping addresses.  (Most  operating  systems  write  over  the  previous 
program's  memory  when  loading  a  new  program.)  OS-9's  tech- 
nique means  that  you  do  not  need  to  be  concerned  with  absolute 
meniory  addresses. 
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Chapter  5 


Useful  System  Information 
and  Functions 


The  OS-9  system  must  load  many  parts  of  the  operating  system 
during  st^tep  mad  ^tem  apmsAm.  Tfa9*fet>  m  a  fbppf  disk 
system,  you  atust  keep  the  system  diskette  in  Drive  /DO. 

Two  files  used  during  the  system  startup  operation,  OS9Boot 
and  Startup,  must  remain  in  the  system  diskette's  ROOT  direc- 
tory. Other  files  on  the  system  diskette  are  organized  into  two 
directories:  CMDS  (commands)  and  SYS  (other  system  files).  You 
can  also  create  other  files  and  dire^iiet  ga  the  sifstiit&  0j^tte. 
OS-9  always  creates  the  initial  data  directory,  or  ROOT  direc- 
tory, when  you  format  a  diskette. 

File  M£^a§ers,  Device  Drivers,  and 
Descriptors 

The  bootstrap  (instructions  that  initialize  OS-9)  loads  a  file 
called  OS9Boot  into  RAM  memory  at  startup.  This  file  contains 
file  managers,  die^ce  drivers  and  descriptors,  and  any  other  mod- 
ules that  permanently  reside  in  memory.  For  instance,  the 
OS9Boot  file  might  contain  these  modules: 


OS9p2  OS-9  Kernel 

INIT  System  Initialization  Table 

lOMan  OS-9  input/output  manager 

RBF  Random  block  (di&)  file  manage 

SCF  Sequential  character  (terminal)  file  manage 

PipeMan  Pipeline  file  manager 

Piper  Pipeline  driver 

Pipe  Pipeline  device  descriptor 

CC3IO  Keyboard/video  gmphibs  igitice  driver 

VDGINT  32x16  screen  subroutines 

GRFINT  Windowing  subroutines 

PRINTER  Printer  device  driver 

SIO  RS-232  serial  port  device  driver 

CC3Disk  Disk  driver 

DO,  Dl  Disk  device  descriptor 

TERM  Terminal  device  descriptor 

Tl  RS-232  serial  port  device  descriptor 

P  Printer  (serial)  device  descriptor 

PI  Printer  CsagriaJ)  device  dei^ipte 
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Clock         Real-time  clock  module 
CC3GO       System  startup  process 
W  -  W7       Window  device  descriptors  W,  Wl,  W2,  W3, 
W4,  W5,  W6,  W7 

OS-9  stores  the  modules  baded  during  the  system  startup  with 
a  mittiiltam  of  fragmentation.  To  include  additional  modules,  cre- 
ate new  bootstrap  files  using  the  0S9GEN  command  or  the 
CONFIG  program  supplied  with  OS-9.  You  cannot  unlink  a  mod- 
ule loaded  as  part  of  i£e  bootstrap. 

After  booting,  when  the  system  switches  the  boot  block  into  its 
own  address  Sl^m^  any  non-system  files  included  in  the  boot- 
strap decrease  the  memory  available  in  the  system  mode.  It  is 

best  to  place  optional  modules  in  a  separate  file  and  load  them 
as  part  of  the  system  startup  procedure.  One  example  is  the 
shell.  Never  include  the  shell  as  part  of  a  system  boot  file  in 
OS-9  Level  Two  systems. 

The  Sys  Directory 

The  OS-9  SYS  directory  contains  a  number  of  important  files: 

•  Errmsg  is  the  error  message  file. 

•  Helpmsg  contains  syntax  and  usage  information. 

•  Stdfonts  contains  the  standard  software  fonts  for  use  on 
graphic  windows. 

•  Stdpats  2,  Stdpats  4,  and  Stdpats  16  contain  screen 

background  and  fill  patterns  for  2,  4,  and  16  color  graph- 
ics screens,  respectively. 

•  Stdtptrs  contains  grapMe  painter  images  for  use  with  a 

mouse. 

These  files,  and  the  SYS  directory  itself,  are  not  required  to  boot 
OS-9,  but  you  do  need  them  if  you  plan  to  use  the  ERROR  or 
HELP  commands,  or  if  you  intend  to  use  text,  or  mouse  pointers 
on  graphic  windows.  You  can  also  add  other  system-wide  files  of 
a  similar  nature. 
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The  Startup  File 

The  Startup  file  (/DO/startup)  is  a  didl  procedure  file  that  OS-9 
automatically  processes  as  part  of  the  system  boot.  You  can 
include  any  legal  shell  command  line  in  the  Startup  file.  Many 
people  include  SETIME  to  start  the  system  clock.  If  this  file  is 
not  present,  the  system  starts  correctly,  but  the  systan  time  is 
not  accurate. 

The  CMDS  Directory 

The  directory  /DO/CMDS  is  the  system-wide  command  directory 
normally  shared  by  all  users  as  their  working  execution  direc- 
tory. The  shell  resides  in  the  CMDS  directory.  The  system  start- 
up process  CC3go  makes  CMDS  the  initial  execution  directory. 

You  can  add  your  own  programs  to  the  CMDS  directory  and  have 
them  execute  in  the  same  manner  as  the  original  system 
commands. 

Making  New  System  Diskettes 

GeUin^  Started  With  OS-9  told  you  how  to  create  new  system 
diskettes  using  the  CONKG  utility.  Tliere  are  other  wjiys  to  cre- 
ate system  diskettes  and  either  add  or  subtract  capabilities.  The 
following  information  provides  guidelines  on  how  to  do  this.  For 
more  detailed  instructions  see  tlie  descrip'^cms  of  the  CONFIG, 
0S9GEN,  and  COBBLER  commands  in  this  manual. 

BefiHre  starting  mlj  of  the  fbliowing  procedures,  you  need  a 
blank,  formatted  <^^tte  on  y>Ms:h.  to  plwse  your  system  files. 
Then,  choose  one  of  the  following  methods  to  update  your 

system: 

•  Use  the  0S9GEN  command  to  add  modules  to  the  exist- 
ing OS9Boot  file. 

•  Use  CONFIG  to  select  the  modules  you  want  to  include 
in  the  OS9Boot  file. 
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If  you  choose  to  use  CONFIG,  the  utility  creates  a  complete  sys- 
tem during  the  process.  If  you  use  0S9GEN,  follow  these  steps: 

1.  Create  the  OS9Boot  file  using  0S9GEN. 

2.  Create  or  copy  the  Startup  file. 

3.  Cqpy  the  CMDS  and  SYS  directcades  and  the  files  th^ 
contain. 

You  can  perform  these  steps  manually  or  do  them  automatically 
by  using  one  of  these  methods: 

•  Creating  and  using  a  shell  procedure  file 

•  Using  a  shell  procedure  file  generated  by  DSiWE 

Technical  InfOFmatlon  for  the  RS-232  Port 

You  can  operate  the  RS-232  port  or  the  printer  at  all  standard 
baud  rates  from  110  baud  to  19200  baud.  (The  default  rate  is 
9600  baud  for  /t2,  and  600  baud  for  /p.)  The  default  format  used 
is  8  data  bits,  no  parity,  and  1  stop  bit. 

Use  the  XMODE  command  to  set  the  port's  baud  rate,  parity, 
word  length,  stop  bits,  end-of-line  delay,  auto  line  feed,  and  so 
forth.  lb  examirae      Pinter's  current  settings,  type: 

xmode  /p  ]mm\ 

Then,  if  you  want  to  make  changes,  use  XMODE  with  informa- 
tion froKi  the  following  chajct.  Select  the  parameter  you  want 
from  the  left  column  of  each  chart,  and  then  select  the  corre- 
sponding number  from  the  "Value  to  Use"  column  and  write  it 
down.  After  you  select  the  proper  value  from  each  chart,  add 
them  together  to  obtain  $.  &eim  Wlvm  for  XMODE.  All  values 
must  be  hexadecimal. 
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Stop  Bits 


Word  Length 


Baud  Rate 


Number  of 
Stop  Bits 

to  Use 

1  Stq)  Bit 

0 

80 

Word 

Value 

Length 

to  Use 

7  Bits 

20 

SBitg 

0 

UiLO  1  CI 

Value 

Second 

to  Use 

110  BPS 

0 

300  BPS 

1 

600  BPS 

2 

1200  BPS 

3 

2400  BPS 

4 

4800  BPS 

5 

9600  BPS 

6 

19200  BPS 

7 

Fbr  instanee,  to  set  the  printer  parameters  to  one  stop  bit,  a 
word  length  of  seven  bits,  and  a  baud  rate  of  600,  select  0  from 
the  Stop  Bits  chart,  20  from  the  Word  Length  chart,  and  2  from 
the  Baud  Rate  chart.  Add  the  values  together: 

0  +  20  +  2  =  22 

The  eommand  to  set  the  printer  port  for  this  eonflguration  is: 


xmode  /p  baad  =  22  |  ENTER  | 

Whm  fisu  use  XMODE  to  set  baud,  parity,  and  stop  bit  values, 
fTO  are  actually  setting  the  bits  of  a  special  byte  to  csertain  val- 
ues.  0S-§  uses  these  •v'alues  to  deterftiilie  how  to  handle  subse- 
quent input/output  operations.  A  bit  is  a  binary  digit  and  can  be 
either  1  or  0.  A  byte  consists  of  eight  bits  and  can  represent  a 
value  between  0  and  255. 

The  following  chart  shows  the  bits  that  control  baud  rate,  word 
length,  and  stop  bits  for  input/output  operations  on  a  specified 
device. 
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Bit 


76543210 


->  Baud  rate 

Reserved 
->  Word  length 
->  Stop  bits 


If  the  stop  bit  value  =  0,  stop  bits  =  1 
If  the  stop  bit  value  =  1,  stop  bits  =  1 

If  the  word  length  value  =  00,  word  length  =  8  bits 


If  the  baud  rate  value  -■ 
If  the  baud  rate  value  • 
If  the  baud  rate  value  ■ 
ff  the  baud  rate  vahie  ■■ 
If  the  baud  rate  value  ■ 
If  the  baud  rate  value  ■ 
If  the  baud  rate  value  ■ 
If  the  baud  rate  value  ■■ 

m  iffilAMK  oiJy) 
If  the  baud  rate  value  ■■ 

(/tl  SIO  only) 

Use  XMDDE  TYPE=vaiue  to  set  parity,  MDM  (modem)  kill,  and 
the  not  ready  delay.  Value  is  a  hexadecimal  value  you  calculate 
from  the  following  chart: 


=  01,  word  length  =  7  bits 

0,  baud  rate  = 

110 

1,  baud  rate  = 

300 

2,  baud  rate  = 

600 

3,  baud  rate  = 

1100 

4,  baud  rate  = 

2400 

5,  baud  rate  = 

4800 

6,  baud  rate  = 

9600 

7,  baud  rate  = 

19200 

7,  baud  rate  = 

32000 

Parity 


1^6  of 

Value 

Psaity 

to  Use 

None 

0 

Marls. 

AO 

Space 

EO 

Even 

60 

Odd 

20 

MDM  Kill 

Kill 

Value 

Switch 

to  Use 

On 

10 

Off 

0 

Not  Ready  Delay 


Not  Ready 

Value 

Delay 

to  Use 

0  seconds 

0 

1  second 

1 

2  seconds 

2 

3  seconds 

3 

♦ 

t 

♦ 

♦ 

t 

15  seconds 

F 
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Select  a  value  from  each  chart,  and  add  them  together  to  get  a 
final  TYPE  value.  For  instance,  to  select  even  parity,  MDM  kill 
off,  and  a  not  ready  delay  of  10  seconds,  select  these  ■values  and 
add  them: 

60  +  0  +  A  =  6A 

To  set  the  new  values,  type: 


xmode    /p    type  =  6a  |  ENTER  | 

The  following  chart  shows  the  bits  that  control  parity,  the 
modem  kill  switch,  and  the  not  ready  delay. 


Bit 


7   6   5   4   3   2  1 


0 


 >  Not  ready  delay 

(printer  only) 

MDM  kiU  switch  (ACIAPAK/ 


Parity 


If  the  parity  value  is  000,  then  parity  =  none 

If  the  parity  value  is  101,  then  parity  =  MARK,  no  check 

If  the  parity  value  is  111,  then  parity  =  SPACE,  no  check 

If  the  MDM  kill  switch  value  is  0,  then  DCD  loss  =  no  kill 
If  the  MDM  kill  switch  value  is  1,  then  DCD  loss  =  kill 

Ths  value  of  the  not  ready  delay  bits  equals  the  number  of 

seconds  delay. 

list  more  information  on  setting  other  parameters,  such  as  the 
emd-of-line  delay  (null  count),  see  the  XMODE  command  refac- 
ence  in  Chapter  6. 


r 
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Chapter  6 


System  Command  Descriptions 


This  chapter  contains  alphabetical  descriptions  of  the  commands 
itipplied  with  OS-9.  Ordinarily,  yaa  call  the  cotntnatids  fl?dm  the 

shell,  but  you  can  also  call  them  from  most  other  programs  in 
the  OS-9  family— including  BASIC09  and  the  Macro  Text  Editor. 

Warning:  Do  not  attempt  to  use  OS-9  Level  One  commands 
with  the  OS-9  Level  Two  system  or  to  use  Levd  Two  com- 
mands with  the  Level  One  system. 


Baefa  offimand  entry  includes: 

•  The  name  of  the  cominaad 

•  A  syntax  line,  whicli  sbsm  ym  the  &am&t  and  spetlu^ 
to  use  when  you  type  the  command 

•  A  brief  definition  of  what  the  command  ism 

•  Information  about  any  options  available  with  the 

command 

•  Notes  about  the  command  and  how  to  use  it 

•  One  or  more  examples  of  command  use 

Command  Syziitax  Notatkms 

OS-9  requires  that  you  enter  the  various  parts  of  a  command  in 
the  correct  order  and  in  the  correct  format.  An  example  of  the 
proper  syntax  follows  the  command  name. 

The  syntax  line  always  begins  with  the  name  of  the  command. 
Occasionally,  that's  all  you  need  (except  for  pressing  I  enter  |).  But 
a&m  mmmsjais  eithi^  require,  w  can  accept,  parameters  (vari- 
ables that  gEve  Instructions  to  OS-9). 


Some  syntaxes  include  variables  (shown  in  italics)  that  you 
replace  with  specific  parameters.  For  instance,  the  BUILD  com- 
mand syntax  is: 

build  filename  I  ENTER  I 


OrganizaticHa  of  Entries 
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BUILD  is  the  command  name.  You  type  it  exactly  as  shown. 
However,  filename  is  a  variable.  Replace  it  "Wit^  ihs  s^tual  name 
you  want  to  give  to  the  file  you  are  creatix^.  If  you  want  to  cre- 
ate a  file  named  Myfile,  type: 


build  myf  He  |  ENTER  | 
Pressing  |  enter  |  executes  the  command. 
Common  variables  are: 


arglist 

deuname 
commandname 
dimame 
filename 

hex 

hhlmmiss 
modname 
n 

number 
O0ts 

paramlist 
pathlist 
permission 
procID 

text 

tickcount 

value 
yylmmidd 


arglist  (argument  list)  is  similar  to  paramlist, 
but  it  includes  command  names  as  well  as 
command  parameters. 

device  name  (/P,  /TERM,  /Ml) 

command  name 

directory  name 

file  name 

a  hexadecimal  number 
hour/minutes/seconds 
name  of  a  memory  module 
a  decimal  number 
a  numeric  value 
options 

a  list  of  parameters 

a  complete  path  to  a  directory  or  file 

file  permission  abbreviations 

process  ID  number 
a  string  of  characters 

a  numeric  value  representing  system  clock 
ticks 

a  numeric  value 
year/month/day 
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[  ]  Bcackets  indicate  that  the  material  within  them  is  optional 
and  not  necessary  for  the  execution  of  the  command. 

...  An  ellipsis  indicates  that  you  can  repeat  the  material  imme- 
diately preceding  the  ellipsis.  For  instance,  {filename\[...'\  means 
that  you  can  specify  more  than  one  filename  to  the  command. 
Pbllowing  is  the  syntax  for  the  DISPLAY  command: 

diaplay  hex  [...]  [InterI 

This  meaiis  you  mm  iiielude  more  than  one  hess  number  with 
DISPLAY,  sudi  as: 

display   54    48   49   53   20    49   53   20    41    20    53  45  43 

52   45   54   20    4D   45   53   53   41    47   45  |  ENTER  | 

Command  syntaxes  do  not  include  the  shell's  built-in  options  (for 
instance  I/O  redirection)  because  the  shell  filters  out  its  options 
before  it  passes  the  command  line  to  the  program  being  called. 

Cottiiiistxid  SWDiinary 

Hus  m^&mx  nksi^bes  tbe  fiirmmt  and  us@  of  QS^0  oommaisis. 
Tbe  fiiitai^iif  list  is  a  summarif  of  emmxands: 


NSrttt  Changes  a  file's  atts4bUti©B 

BACKUP  Makes  a  copy  of  a  diskette 

BUILD  Builds  a  text  file 

CHD  Changes  the  working  data  directory 

CHX  , . . ,  , ,  Ctenges  the  working  execution  directory 

Clip  Compares  flies 

COBraL£R  . . .  Makes  an  OS9Boot  file 

CONFIG  Creates  a  system  diskette  to  your  specifications 

COPY  Copies  data 

DATE  Displays  the  system  date  and  (optionally)  the 

time 

DCHECK  Checks  a  disk  file  structure 

DEINIZ  Deinitializes  a  device  previously  initialized  with 

INIZ 

DEL  . . . . .  Deletes  a  file  or  files 

IMLDCR  ,  Deletes  a  directory's  files,  then  deletes  the 

directory 

DIR  Displays  the  names  of  all  files  in  a  directory 

DISPLAY. ....  Displays  the  characters  repres^ted  hy  hexadeci- 
mal values 

DSAVE  Generates  a  procedure  file  to  copy  files 
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ECHO   Echoes  text  to  the  screen 

EDIT   Calls  the  OS-9  Macro  Text  Editor 

ERROR  Displays  a  description  of  the  last  error  code 

EX ...  1  Causes  the  shell  process  to  execute  another 

process 

FORMAT  ....  Prepares  a  disk  for  data  storage 

FREE  Displays  the  amount  of  free  space  on  a  disk 

HELP  Displays  the  syntax  and  use  of  commands 

IDENT  ^isjg^^ys        module  identification 

1NM  MCializes  art  attaches  devices 

KILL   Terminates  a  process 

LINK  Links  a  module  into  memory 

LIST  Lists  the  contents  of  disk  data  files 

LOAD  Loads  a  module  into  memory 

MAlffiilR   Creates  a  directory 

MDIR  Displays  the  names  of  the  modules  in  naeanory 

MERGE  Copies  and  combines  files 

MFREE  Displays  a  list  of  free  RAM 

MODEA.TCH . .  Makes  changes  to  a  module  in  mssmotpy 
MONTYPE  . . .  Establishes  the  type  of  monitor  in  use 

OS9GEN  Builds  and  links  a  bootstrap  file 

PROCS  Displays  the  names  of  the  current  processes 

P WD  Displays  the  nspotfi  of  the  current  data  directory 

PXD  Displ^s  the  name  of  the  current  execution 

directory 

RENAME  ....  Changes  the  name  of  a  file  or  directory 

SETIME  Activates  and  sets  the  system  clock 

SETPR  Sets  a  process's  priority 

SHELL  . .  Creates  a  child  shell  to  process  one  or  more 

commands 

TMODE  Changes  the  terminal's  operating  mode 

TUNEPORT    Adjusts  the  loop  delay  for  the  baud  rate  of  /?  or 

/Tl  devices 
UNLINK  Unlinks  memory  modules 


WCREATE  . . .  Creates  a  window 

XMODE  Displays  or  changes  a  device's  initialization 

parameters 
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ATTR 

^snmtax:    attr  Glename  [pennission] 

Function:  Lets  you  examine  or  change  a  file's  security 
pamissions. 

Parameters: 

filename  The  name  of  the  file  you  want  to  examine  or 

change. 

permission  One  or  more  of  the  following  attribute  options. 
Options: 

The  £Qe  permission  abbreviations  you  can  use  are: 

•d  Chains  a  file  directory  file  to  Bot  a  non-direct(xry 
file, 

s         Specifies  that  the  file  is  not  single-user  and  can  serve 

only  one  user  at  a  time. 

r  Specifies  that  only  the  owner  can  read  the  file. 

w  Specifies  that  only  the  owner  can  write  to  (change) 
the  file. 

e         Specifies  that  only  the  owner  can  execute  the  file. 

pr       Specifies  that  the  public  (anyone)  can  read  tiie  file. 

pw      Specifies  that  the  public  (anyone)  cam  write  to  the  file. 

pe        Specifies  that  the  public  (anyone)  can  execute  the  file. 

-a  Tells  ATTR  not  to  display  the  attributes.  Use  this 
option  when  you  wish  to  change  attributes  without 
dl^Iaying  thatn. 
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Notes: 

•  To  use  ATTR,  type  the  con^tnand  name  followed  by  the 
name  of  the  file  yoll  -wsast  to  change.  Next,  tjrpe  a  list  of  the 

permissions  to  turn  on  or  off.  Turn  a  permission  on  by  typ- 
ing its  abbreviation  or  off  by  typing  its  abbreviation  pre- 
ceded by  a  minus  sign.  ATTB  has  no  dlfect  on  permissions 
you  do  not  name. 

•  If  yptt  do  not  specify  any  permissions,  ATTR  displsgrs  the 
fite's  cui¥@at  attributes. 

•  %u  cannot  change  the  attrihtites  of  a  flli  fou  don-t  own. 
Ui^  0  can  change  the  attributes  of  any  file     Ihe  ^stem. 

•  Use  ATTR  to  change  a  directory  into  a  file  after  deleting 
all  the  directory's  files.  You  cannot  change  a  file  to  a  direc- 
tory with  ATTR.  (See  MAKDIR.) 

Examples: 

•  To  remove  public  read  and  write  permission  from  a  file 
named  Myfile,  type: 

atti*  myfile  -pr  "pw  [ENTER I 

•  To  give  read,  write,  and  execute  pmnission  to  everyone  for 
the  file  Myfile,  type: 

attr  myfile  r  w  e  pr  pw  pe  |  ENTER  | 

•  To  display  the  current  permissions  of  a  file  named  Datalog, 
type: 

attr  datalog  | ENTER | 
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BACKUP 


^smtax:  backup  [optsl[devnamel]ldevname2\ 
Function:  Copies  all  data  from  one  disk  to  another. 


Parameters: 

devnamel        The  drive  containing  the  disk  fQes  you  want  to 
back  up. 

dmmm^       The  drive  e<mtaining  fee  ^sk  to  which  you 
want  to  transfer  the  files, 

opts  One  or  more  (£  the  folbwing  options. 


Options: 


e  Cancels  the  backup  if  a  read  error  occurs. 

s  Lets  you  backup  a  diskette  using  only  one 

drive. 

-V  Tells  BACKUP  not  to  verify  the  data  written 

to  the  destination  diskette. 

#nK  Increases  to  n  the  amount  of  memory  that 

BACKUP  can  use.  Increasing  the  amount  of 
memory  assigned  to  BACKUP  speeds  the  pro- 
cedure, n  can  be  either  ki  pa^es  of  2i@  hylss 
or  in  kilobytes  (1024  hytes).  Include  K  to  indi- 
cate kilobytes. 


Notes: 


•  BACKUP  performs  a  sector  by  sector  copy,  ignoring  file 
structures.  In  all  cases,  the  devices  specifild  must  hKve  the 
same  format  (size,  density,  and  so  forth)  and  the  destina- 
tion disk  must  not  have  defective  sectors. 
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•  If  you  omit  both  device  ioaxties,  the  system  assuxQes  ]ifm  are 
copying  from  /D®  to  /DL  Wfou  omit  oni^  iiie  mcxmA  (teivice 
name,  QS-9  performs  a  single'drive  backup  on  the  specified 

drive. 


•  The  following  demonstrates  a  complete  backup  of  /DO  to 
/Dl.  In  the  example,  the  diskette  in  Drive  /Dl  is  a  format- 
ted diskette  with  the  name  MYDISK.  Scratched,  which 
appears  in  one  of  the  following  messages,  means  erased. 
Yaa  type: 

bac  kup  I  ENTER  I 

The  screen  display  and  your  input  are: 

Ready  to  backup  from  /d0  to  /dl   ?:  [7] 
MYDISK 

Is  being  scratched 
DK?:  [Y] 

Sectors   copied:  $0276 
Verify  pass 

Sectors  verified:  $0276 

•  Following  is  an  example  of  a  single-drive  back  up.  BACKUP 
reads  a  p ortldn  of  the  source  diskette  (the  diskette  you  are 
copying)  into  memory.  It  then  prompts  you  to  remove  the 
source  diskette  and  put  the  destination  diskette  (the 
diskette  receiving  the  copy)  into  the  drive. 

After  BACKUP  writes  to  the  destination  diskette,  remove 
the  destination  diskette  and  put  the  source  diskette  back 
inlQ  the  #im  (l(»alifiWd  s«iFa|i|nng  as  prompled  until 
MMMJJW  mpm  ^  didaette. 

Giving  BACKUP  as  much  memory  as  possible  means  you 
have  to  make  fewer  diskette  exchanges.  If  enough  free  mem- 
ory is  available,  you  can  assign  up  to  56  kilobytes  for  the 
backup  operation.  An  Error  207  means  that  your  computer 
does  not  have  the  spee&d  amount  of  memory  free.  To 
assign  32  kilol^ytes  to  backup,  type: 

backup  /da  *32k  I  ENTER  I 
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The  ■^mtmm  iisplaf  and  ycm  mspQixses  are  as  follows: 

Ready  to   backup   from   /d0   to  d0   ?:  {Tj 
Ready  Destination,    hit   a   key:  |  ENTER  | 
MYDISK 

is  being  scratched 
OK?:  (Y) 

Ready  Source,    hit  a   key:  |  ENTER  | 
Ready  Destination,    hit   a    key:  |  ENTER  | 
Ready  Source,    hit  a   key:  |  ENTER  | 
Ready  Destination,   hit  a  key:  |  ENTER  | 


I 

Ready  Destination,   hit   a   key:  |  ENTER  | 
Sectors  eofj-Ied:  10276 
Verify  pass 

Sectors  verified:  $0276 

In  this  procedure,  the  dollar  symbol  ($)  indicates  hexadeci- 
mal numbers.  BACKUP  copied  276  hexadecimal  (or  630 
decimal)  sectors. 

Examples: 

•  To  back  up  the  diskette  in  Drive  /D2  to  the  diskette  in 
Drive  ZDS,  type: 

backup  /d2  /d3  |  ENTER | 

•  To  back  up  from  Drive  /DO  to  Drive  /Dl,  without  verifica- 
tion, type: 

backup    -V  I  ENTER  | 
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BUILD 


Function:  Builds  a  text  file  by  copying  input  from  the  stan- 
dard input  device  (the  keyboard)  into  the  file  specified  by 


•  BUILD  creates  a  file,  naming  ftlemme.  B  l&en  displays  a 
question  mark  (?)  and  waits  for  you  to  type  a  line.  When 
you  type  a  line  and  press  |  enter  |,  BUILD  writes  the  line  to 
the  di^. 

•  When  you  finish  entering  the  lines  for  the  new  file,  press 
I  iENTER  I.  without  acgr  preceding  text,  to  close  the  file  and  ter- 
minate the  operation. 

•  The  following  example  demonstrates  how  to  build  a  text  file 
named  Newfile: 

build  newfile  lENTBRI 

?   THE   POWERS  DF  THE  05-9  ["enterI 
?   OPERATING  SYSTEM  ARE  TRULY  |  ENTER  | 
?   FANTASTIC.  |  ENTER  | 
?  I  ENTER  I 

•  To  view  the  newly  created  file,  type: 

list   newfile  |  ENTER  | 


Parameters: 


filemme 


The  name  of  the  file  you  are  creating. 


Notes: 
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The     effi.  displays: 

THE  PQWEii  DF  THE  OS -9 
DPERATIN©  SYSTEM  ARE  TRULY 
FfiNTASTIC. 


Examples: 

•  To  create  a  file  called  Small—file  and  put  into  it  wihat- 
ever  jou  lyp©  at  the  keyboard,  tjrpe: 

build  small—f  ile  [gSD 

•  To  direct  ^ibat«^  you  type  to  the  printer,  type: 

build  /p  I  ENTER  I 

•  You  can  use  BUILD  to  transfer,  or  redirect,  data  from  one 
file  to  another.  Instead  of  the  keyboard,  this  example  uses  a 
file  named  Mytext  file  for  the  input  device.  The  output 
device  is  Terminal  1. 


build  <mytext   /t1  |  ENTER  | 
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CHD 
CHX 


^^tax:    chd  patblist 
cbx  patblist 

Function:  CHD  changes  the  current  working  (data)  directory, 
and  CHX  changes  the  current  execution  directory. 

Parameters: 

pathlist  l^ecifies  the  directory  for  the  ea»ent  working 

or  execution  directory. 

Notes: 

•  CHD  and  CHX  do  not  appear  in  the  CMDS  directory 
because  they  are  built  into  the  shell. 

Examples: 

•  To  change  the  current  working  (data)  directory  to  the  PRO- 
GRAMS data  directory  located  on  the  diskette  in  Drive 
/Dl,  lype: 

chd  /d1 /programs  (JNTER] 

•  To  change  the  execution  directory  to  the  parent  directory  of 
the  current  execution  directory,  type: 

chx    .  .  I  ENTER  I 

•  To  change  the  execution  directory  to  TEXT_PROGRAMS, 
a  subdimtiEay  of  BINARy_FILlS,  ty|ie: 

chx  binary_f  i les/text  progrania  lENTeflj 
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•  To  return  the  execution  directory  and  the  data  directory 
back  to  the  default  directories,  type: 

chx   /d0/cmd5;    chd   /  d  0  |  ENTERI 

Or,  if  you  are  using  a  hard  disk,  type: 
chx   /h0/cmd5;    chd  /h0  |  ENTER  | 
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CMP 


Syntax:     cmp  filenamel  filename2 


Functiott:  Opens  two  files  and  compares  the  binary  values  of 

corresponding  data  bytes  in  the  files.  If  CMP  encounters  any 
differences  in  the  file,  it  displays  the  file  offset  (address)  and 
the  values  of  the  bytes  from  each  file. 


filenamel         are  ihe  files  to  compare. 

filename2 


Notes: 

•  The  comparison  ends  when  CMP  encounters  an  end-of-file 
marker  in  either  file.  CMP  then  displays  a  summary  of  the 
number  of  bytes  compared  and  the  number  of  differences 
found. 


Examples: 

•  To  compare  two  files  named  Red  and  Blue,  type: 


cmp   red   blue  |  ENTER  | 

Following  is  a  sample  screen  display: 

Differences 

byte  #1  #2 


00000013       00  01 

00000022       B0  B1 

0000002A       9B  AB 

0000002B       3B  36 

0000002C       6D  65 

Bytes  compared:  0000002D 
Bytes  different:  00000005 
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•  To  compare  two  files  that  are  idi^itical,  such  as  Redl  and 

Red2,  type: 

cmp   redl    red2  |  ENTER  | 
The  screen  display  might  be: 
Differences 

None   . . . 

Bytes  compared:  0000002D 
Bytes   different:  00000000 
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COBBLER 


Syntax:     cobbler  devname 

Function:  Crmtes  the  OS9Boot  file  required  on  any  OS-9  boot 
diskette. 


Parameters: 

devname  The  disk  drive  containing  the  diskette  on 

which  you  want  to  create  a  new  OS9Boot  file. 

Hotes: 

•  CCffiKER  emttes  the  new  OS9Boot  file  wffch  the  mm 
modules  loaded  during  the  most  recent  bootstrap.  (To  add 
modules  to  the  bootstrap  file,  use  0S9GEN.)  COBBLER 
also  writes  the  OS-9  kernel  on  Track  34  and  excludes  these 
sectors  fi-oxn  the  diskette  allocation  map.  If  any  files  are 
present  on  these  sectors,  COBBLEK  displays  an  error 
message. 

•  The  new  boot  file  must  be  contiguous  on  the  diskette.  For 
this  reason,  you  should  use  COBBLER  only  with  a  newly 
formatted  diskette.  If  you  use  COBBLER  m.  a  diskette  that 
does  not  have  a  storage  block  large  enough  to  hold  the  boot 
file,  COBBLER  destroys  the  old  boot  file,  and  OS-9  cannot 
boot  from  that  di^tte. 

•  To  change  device  attributes  permanently,  use  XMODE 
before  using  COBBLER. 

^mmples: 

•  To  save  the  attributes  of  the  cuirent  device  on  the  systete 
diskette,  type: 

EBb;bie:f»    /rf0  I  ENTER  | 


6-16 


System  Command  Descriptions  I  6 


If  you  use  COBBLER  on  a  diskette  that  is  not  newly  format- 
ted, the  screen  displays: 

WARNING  -  FILECS)  OR  KERNEL 

PRESENT  OH  TRACK   34   -  THIS 
TRACK  NOT  REWRITTEN 
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CONFIG 


Function:  Lets  you  create  a  system  diskette  that  includes  only 
the  device  dzxvi^  aad  efmmmiSs  you  ideet.  CCB^@  auto- 
matically  adjusts  its  screen  display  fbr  either  32-  or  80-colmnn 
display. 

Notes: 

•  When  executed,  CONFIG  displays  menus  of  all  I/O  options 
and  system  commands.  You  select  only  those  options  and 
commands  jaa  want  to  include  on  a  new  system  diskstte. 

Creating  STxch  a  system  diskette  lets  you  msiSm  raosi 
efficient  use  of  computer  memory  and  system  diskette 

storage. 

•  The  CONFIG  utility  is  on  the  BASIC09/CONFIG  dinette. 
Copy  this  di^tte,  using  the  OS-9  BAGKTJP  eoimnaiid. 
Make  the  copy  your  working  diskette.  Keep  the  original  in 
a  safe  place  to  use  for  future  backups.  After  you  boot  your 
system,  you  can  put  the  working  copy  of  ^le  BAMC09/ 
CONFIG  diskette  in  drive  /dO.  Then,  type  these  commands: 

chx   /dB/cmds;   chd  /d0/module5  |  ENTER] 

•  CONFIG  does  not  require  initial  parameters.  You  establish 
parameters  during  t&  operation  of  fbe  (sommand.  Be  stire 
the  execution  directory  is  /DO/CMDS  before  executing 

CONFIG. 

•  You  could  save  time  by  using  BACKUP  to  create  a  system 
disk,  using  CONFI©  to  create  a  new  boot  file,  and 
deleting  unwanted  commands.  However,  this  process  causes 
fragmentation  of  diskette  space  and  results  in  slower  disk 
access.  CONFIG  causes  no  fragmmitation. 
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•  The  MODULES  directory  of  the  BASIC09/CONFIG  diskette 
contains  all  the  device  drivers  and  device  descriptors  sup- 
ported by  OS-9.  The  filename  extension  describes  the  type 
of  file,  as  noted  in  the  following  table: 


Extension 

Module  Type 

.dd 

Device  Descriptor  module 

.dr 

Device  Driver  module 

.io 

Input/Output  subroutine  module 

.hp 

Help  file 

.dw 

Window  Device  Descriptor  module 

.dt 

Terminal  Device  Descriptor  module 

.mn 

Pile  Mana^  inodule 

Examples: 

The  following  steps  take  you  through  the  complete  CONFIG 

process: 

1.  With  the  BOOT/CONFIG  diskette  in  the  current  drive, 
type: 

conf  ig  |  ENTER  1 

2.  CONFIG  adss  whether  you  want  to  use  one  or  two  disk 
drives.  Press  (T)  for  single-  or  [2]  for  two-drive  operation. 

If  you  specify  one  drive,  continue  with  Step  3. 

If  you  gpeeify  two  drives,  a  display  asks  you  to: 

ENTER  NAME  OF  SOURCE  DISK: 
Type  /d0  I  ENTER  I 

A  display  now  asks  you  to: 

ENTER  NAME  OF  DEST.  DISK: 
Type  /d1  [ENTER  | 

3.  After  a  pause  to  build  a  descriptor  list,  the  program  dis- 
plays a  list  of  the  various  devices  from  the  MODULES 

directory.  Use  [T]  and  [T]  to  move  to  a  device.  To  include 
the  device  on  the  system  diskette,  press  (T)  once.  CONFIG 
disid^a  an  X  by  the  selected  device,  lb  occlude  a  selected 
device,  press  (T)  again  to  erase  the  X, 
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A  special  help  command  provides  information  about  each 
device.  To  display  information  about  the  current  device  (the 
device  indicated  by  the  arrow  (-►)),  press  (T|. 


The  list  of  devices  might  require  more  than  one  screen.  Use 
F^l  to  move  ahead  page  by  page  and       to  move  back. 

The  devices  you  can  select  and  their  descriptions  are  listed 
in  Ghapter  2  under  the  seetkoi  "Device  Names." 

Yon  must  select  a  "DO"  device  as  your  first  disk  diivtt. 

Select  from  the  list  of  D  devices  for  other  floppy  disk  drives. 
Select  P  to  use  a  printer  with  OS-9,  Tl  to  use  a  terminal, 
Ml  to  use  a  modem,  and  so  on. 

4.  After  selecting  the  devices  you  desire,  press  [T).  The  screen 
displays,  are  YQU  sure  cy/N)  ?  If  you  are  satisfied  with 
faaur  sdeeltes,  p^ms  (T).  If  you  want  to  make  changes, 
press  (T). 

5.  To  use  your  computer  keyboard  and  video  display,  you  must 
select  either  TERM_VDG  or  TERM_WIN.  You  use 
TERM_VDG  for  a  32-column  display.  For  a  TERM  window 
that  enables  you  to  select  character  displays  up  to  80-col- 
umns,  sdeet  tlSICJWlN. 

6.  CQNFIQ  builds  a  boot  list  from  the  selected  devices  and 

their  associated  drivers  and  managers  in  the  MODULES 
directory  of  the  current  drive.  It  next  displays  two  clock 
options: 

1  -  60HZ  (AMERICPIN  POWER) 

2  -   50H2  (EUROPEAN  POWER) 

7.  If  you  live  in  the  United  States,  Canada,  or  any  o1^@r  wasx- 
try  with  @01iz  dectrical  power,  press  (T|.  If  you  li-ve  in  a 
country  with  50hz  power,  press  [f]. 

If  you  have  a  single  disk  drive,  a  screen  prompt  asks  you  to 
swap  diskettes  and  press  [c].  When  asked  for  the  SOURCE 
diskette,  insert  the  BASIC09/CONFIG  diskette.  When 
asked  for  the  DESTINATION  diskette,  insert  the  diskette 
thai  Is  t&  be  your  new  03^9  syst^  eQtwgt^. 


If  you  have  more  than  one  drive,  a  so^en  prompt  asks  you 
to  insert  a  blank  formatted  diskette  (the  DESTINATION 
diskette)  in  the  destination  drive.  The  rest  of  the  boot  file 
creation  is  automatic. 
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8.  After  creating  the  boot  file,  CONFIG  displays  a  menu  of  the 
wsxmmMa  ym  can  include  on  ym  system  diskette.  ISsa 
have  the  Mlowing  choices: 

[N]o  Commands,  Stop  Now  —  Do  not  add  any  commands 
[Flail  Command  Set  — Add  all  OS-9  commands 

from  the  current  CMDS 

directory 

[  I  Individual  ly  Select     — Select  commands  one  by 

one 

EH]  Receive  Help  —  Get  help  on  the  command 

set 

Press  (T|  if  you  want  to  transfer  a  new  boot  file  to  a 
diskette  on  which  you  have  previously  copied  the  OS-9  sys- 
tem. If  you  have  only  one  <fisk  drive,  this  procedure  is 

quicker  than  using  the  CONFIG  utility  to  complete  the 
entire  system  transfer,  because  it  requires  fewer  disk 
swaps. 

Press  (T)  to  make  an  exact  copy  of  the  CMDS  directory  an 
your  source  diskette  with  a  new  boot  file. 

Press  Q]  to  individually  select  commands  to  mg^  on  the 
new  dinette.  The  □  option  displays  a  menu  similar  to  the 
device  selection  screen.  Press  [T]  to  select  or  exclude  com- 
mands, and  use  the  arrow  keys  to  move  among  the  com- 
mands in  the  menu.  CONFIG  selects  files  marked  wi;^  an 
X  for  inclusion  on  the  new  system  diskette.  If  a  command 
does  not  have  an  X  beside  it,  CONFIG  excludes  it  from  the 
new  system  diskette. 

9.  If  you  have  a  multi-drive  system,  a  prompt  appears  asking 
you  to  insert  your  OS-9  system  diskette  in  the  destination 
drive.  Press  mm  apa^  bar.  "Hie  lajoc^  finishes  the  CON- 
FIG «p8aittD3a,  aai  mrnm  to  OS-9. 

If  you  have  a  single-drive  system,  you  swap  diskettes  dur- 
ing the  final  process.  This  time,  the  SOURCE  diskette  is 
the  OS-9  System  diskette.  The  DESTINATION  diskette  is 
the  system  diskette  you  are  creating.  The  number  of  swaps 
ie|>e^ds  on  the  number  of  qptions  you  select. 

Note:  When  using  OONFIG  ym  do  not  have  to  use 
your  system  diskette  as  the  source  diskette  to  install 
the  commands.  The  program  can  use  any  diskette 
that  contains  a  CMDS  directory. 
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COPY 


%iitax:    copy  palMiatl  patbUst2  [opts] 

Function:  Copies  data  from  one  file  or  device  to  another  file  or 
device. 


Parameters: 

pathlisti         The  name  of  the  existing  file  or  device  from 

which  you  want  to  copy. 

pathlist2  The  name  of  the  device  or  file  to  receive  the 
copy.  If  you  are  copying  data  to  a  file,  the  file 
must  not  already  exist. 


Options: 

-s  Causes  COPY  to  perform  a  single-drive  copy 

opetaiA&x.  pathlist2  must  be  a  full  pathlist  if 
you  use  -s.  In  a  single-drive  procedure,  COPY 
reads  a  portion  of  the  source  disk  into  memory 
and  then  asks  you  to  exchange  the  source  and 
the  destination  diskette  and  press  [c],  COPY 
nigM  you.  lo  m^mass  diskslles  smral 
times  before  it  completes  duplicating  the 
entire  file. 

#7i[K]  Allows  the  use  of  more  memory  for  the  COPY 

procedure.  If  you  specify  K,  n  represents  the 
amoimt  of  memory  you  want  to  use,  in  units  of 
1024  hytes.  If  you  do  not  spedl^  K,  n  repre- 
sents the  number  of  256-byte  memory  pages. 
Using  this  option  can  increase  speed  and 
reduce  the  number  of  diskette  swaps  required 
&r  single-drive  copies. 
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Notes: 

•  lfpathlist2  is  a  disk  file,  COPY  automatically  creates  it.  Data 
can  be  of  any  type,  and  COPY  does  not  modify  the  file  in  any 
way. 

•  COPY  does  not  add  important  codes  (for  example,  line  feeds). 
Use  LIST  instead  of  COPY  when  sending  a  text  file  to  a  ter- 
minal or  printer. 

•  Following  is  an  example  of  the  screen  display  and  your 
responses  for  COPY  using  a  single  drive: 

copy  /c|0/cat  /£i0y^anlmals/6at  -s  #32k  |  enter  | 
Ready  DESTINATION,   hit  C  to  continue:  [c] 
Ready  SOURCE,    hit   C   to  continue:  [c] 
Ready  DESTINATION,  hit  C  to  continues  jT| 

♦ 

This  example  assigns  32  kilobytes  of  memory  for  COPY  to 
use.  If  enough  free  memory  is  available,  you  can  specify  up 
to  56  kilobytes.  Copy  continues  asking  you  to  swap  the 
source  and  destination  diskettes  until  the  transfer  is 
complete. 

Examples: 

•  To  copy  Filel  to  File2  using  16K  of  memory,  type: 

copy  filel    file2  #15k  |  EMTER  | 

•  To  copy  the  News  file  on  the  diskette  in  Drive  /Dl  to  a  new 
file  named  Messages  on  the  diskette  in  Drive  /DO,  type: 

copy  /d1/joe/news  /d0/peter/m  e  a  g  a  c^e  s  |  ENTER  | 


6-23 


OS -9  Commands  Reference 


DATE 

Syntax:    date  [t] 

Function:  Displays  the  current  date. 

Options: 

t  Causes  the  time  to  appear  with  the  date. 

Notes: 

•  Ibllowing  is  an  example  of  how  to  use  SETIME  to  set  a  new 
date  and  time  for  the  system  and  how  to  use  DATE  to 
check  system  date  and  time: 

set  ime  |  ENPB I 

A  possible  screm  display  and  your  responses  follows: 

yy/mm/dd  hh.mm.ss 
Time?     86/08/22     1  4.19.00  UnTERI 

date  I  ENTER  [ 

August  22,  1986 

date  t  I  ENTER  | 

August  22,   TS16  14.20.20 

Examples: 

•  To  display  the  system  date  and  time,  type: 

date  t  I  ENTER  ! 

•  To  direct  the  DATE  command's  output  to  the  printer,  type: 

date  t  >/p  I  ENTER  | 
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DCHECK 


m.    ^Bhmmk  h^H^  devname 


Functicrn:  Checks  a  disk's  file  structiufe. 


Parameters: 

devmme 


The  disk  drive  to  check. 

One  or  more  of  the  following  options. 


Options: 


-w  =  pathlist 
-m 

-0 


Counts  the  number  of  directories  and  files  and 
displays  the  results.  This  option  causes 
DCHECK  to  chieck  only  the  file  deseriptoris  for 
accuracy. 

Suppresses  listing  of  unused  clusters  (clusters 
allocated  but  not  in  the  file  structure). 

Prints  pathlists  for  questionable  clusters. 

Specifies  a  path  to  a  directory  for  work  files. 

Saves  allocation  map  work  files. 

Prints  DCHECK's  valid  options. 


Notes: 


Sometimes  the  system  allocates  sectors  on  a  disk  that  are 
not  actually  associated  with  a  file  or  with  the  diA's  free 
space.  This  situation  can  happen  if  you  remove  a  disk  from 
a  drive  while  files  are  open.  You  can  use  DCHECK  to 
detect  this  condition,  as  well  as  check  the  geoBral  integrity 
of  directory/file  links. 
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•  After  verifying  and  printing  some  vital  file  structure 
parameters,  DCHECK  follows  pointers  down  the  disk's  file 
system  tree  to  all  directories  and  files  on  the  disk.  As  it 
does  so,  it  verifies  the  integrity  of  the  file  descriptor  sec- 
tors, reports  any  discrepaiieies  in  the  directtoy/ftle  liftks, 
and  builds  a  sector  allocation  map  from  the  segment  list 
associated  with  each  file.  If  any  file  descriptor  sectors 
(FDS)  describe  a  segment  with  a  cluster  not  within  the  file 
structure  of  the  disk,  DCHECK  displays  a  message  like 
this: 

»»»  Bad  FD  segment  Itxxxxxx-tyyyyyy')  for  file: 
CpathUst} 

This  message  indicates  that  a  segment  starting  at  sector 
xxxxxx  and  ending  at  sector  yyyyyy  is  not  on  the  disk.  If 
any  of  the  file  descriptor  sectors  are  bad,  the  entire  FD 
might  be  defective.  DCHECK  does  not  update  the  alloca- 
Um  map  for  corrapt  WIM. 

•  While  building  the  allocation  map,  DCHECK  also  enstires 

that  each  disk  cluster  appears  once  and  only  once  in  the  file 
structure.  If  it  discovers  duplication,  DCHECK  displays  a 
message  like  this: 

Cluster  ixxxxxx  was  previously  allocated 

iWs  m^age  indicates  that  DCHECK  has  found  cluster 
XXX3CXX  more  than  once  in  the  file  structure.  DCHECK 
reprints  the  message  each  time  a  cluster  appeeirs  in  more 
than  one  file. 

Then,  DCHECK  compares  the  newly  created  allocation  map 
with  the  allocation  map  stored  on  the  disk  and  reports  any 
differences  with  messages  like  these: 

Cluster  txxxxxx  in  elloeation  map  but  not  in  file 
structure 

Cluster  txxxxxx  in  file  structure  but  not  in 
allocation  map 

The  first  message  indicates  that  sector  number  xxxxxx 
(hexadecimal)  is  not  part  of  the  file  system,  but  the  disk's 
allocation  map  has  assigned  it  FORMAT  might  exclude 
mm  sectors  from  the  aUocalion  map  because  they  are 
defective. 
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The  second  message  indicates  that  the  cluster  starting  at 
sector  ocxxxxx  is  part  of  the  file  structure,  but  the  disk's 
allocation  map  has  not  assigned  it.  Later  operations  might 
allocate  this  cluster,  overwriting  the  contents  of  the  cluster 
with  data  from  the  newly  allocated  file.  (Clusters  that 
DCHECK  previously  allocated  can  have  this  problem.) 

•  DCHECK  builds  its  disk  allocation  map  in  a  file  called 
pathlistfDCHECKppO,  where  pathlist  is  specified  by  the  -W 
option  and  pp  is  the  process  number  in  hexadecimal.  Each 
bit  in  this  bitmap  file  corresponds  to  a  cluster  of  sectors  on 
the  disk.  If  you  use  the  -p  option,  DCHECK  creates  a  sec- 
ond bitmap  file  (/)ct^/^Zis^2/DCHECKppl)  that  has  a  bit  set 
for  each  cluster  DCHECK  finds  as  "previously  allocated"  or 
"in  file  structure  but  not  in  allocation  map."  DCHECK 
then  makes  another  pass  through  the  directory  structure  to 
determine  the  pathlists  ht  &ese  qtiesMonaMe  etaatem.  fci 
can  save  the  bitmap  work  files  by  speei^ng  the  -m  option, 
on  the  command  line. 

•  For  best  results,  DCHECK  should  have  exclusive  access  to 
the  disk  being  checked.  Otherwise,  the  command  might  be 
fooled  by  a  change  in  the  disk  allocation  map  while 
DCHECK  is  building  a  bitmap  file.  DCHECK  cannot  pro- 
cess disks  with  more  than  39  levels  of  directories. 

•  -p  causes  DCHECK  to  make  a  second  pass  through  the  file 
structure  and  print  pathlists  for  clusters  that  are  not  in  the 
allocation  map  but  are  allocated  or  existing  in  a  file 

structure. 

-w  tells  DCHECK  where  to  place  its  allocation  map  WPCk 
file(s).  The  specified  pathlist  must  be  a  full  pathlist  %t  a 
directory.  (DCHECK  uses  directory  /DO  if  you  do  not  spec- 
ify -w.)  If  you  doubt  the  structure  integrity  of  the  diskette 
being  checked,  do  not  place  the  allocation  map  work  files  on 
that  diskette. 


Examples: 

•  The  following  two  examples  demonstrate  DCHECK 

sessions: 

dchec  k    /d2  |  ENTER  | 
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A  sample  screen  display  might  be: 

Volume  -   'My  system  disk'  on  device  /dZ 

*009fl  bytes  in  allocation  map 

1    sector   per  cluater 

$000276  total   sectors  on  media 

Sector   $000002   is  start  of  Root  directory 

FD 

$0010  sectors  used  for  Id,  allbcatl&St  map 
and  Root  directory 

Building  allocation  map  work  file... 
Checking  allocation  map  file... 

'My  5y5tein  disk '  file  structure  is  intact 

1  direct  ory 

2  files 


dcheck  -mpw=/d2  /d0  I  ENTER! 

A  sample  screen  display  might  be: 


Volume   -    'System  diskette'  an  device  /d0 

$0046  bytes   in  allocation  map 

1   sector  per  Cluster 

$00022A   total   sectors  on  media 

Sector    $000002    is    start    of    Root  directory 

FD 

$0010  sectors  used  for  id,  allocation  map 
and  Root  directory 

Building  allocation  map  work  file... 

Cluster  #00040  was  previously  allocated 

**»    Bad    FD    segment    C $  11 1 1 1 1  - $23A6F 0 )  for 

file:    /D0/TEXT/junky.f ile 

Checking  allocation  map  file... 

Cluster    $000038   in  file  structure  but  not 

in  allocation  ma p 

Cluster  tBigWSM  in  file  structure  but  not 
in  a  1 1  DC  a  1 1  en  ms  p 

Cluster  *000iB9  in  allocation  map  but  not 
in  file  structure 

Cluster  $0001BB  in  allocation  map  but  not 
in  file  structure 
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Pathlists   for   questionable  clusters; 


Cluster   $000038   in  path: 

Cluster    $00003B    in  path: 

Cluster  $000040   in  path; 

double. file 


/d0/DS9boot 
/d0/OS9boot 
/d0/DS9boot 

paths  /tff/t«st/ 


1  prewlsusly  allocated  elusters  found 

2  clusters  in  file  structupe  but  not  in 
al  locat  ion  map 

2  clusters  in  alio  c  a  tion  map  but  not  in 
file  structure 

1  bad  file  descpiptof  sectop 


'System  diskette'  file  structure  is  riot 
intact 

i  dipectoPies 
25  files 
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DEINIZ 


Syntax:     deiniz  devname  [...] 
Function:  Demitializes  and  detaches  a  device. 


Parameter: 

devname         The  name  of  one  or  more  deAfices  you  want  to 
deinitiaUze. 


Notes: 

•  Use  DEINIZ  with  INIZ.  For  sample,  you  ■mm  ma  JNM  to 
Initialize  a  winddw,  then  redirect  infepmattei  to  the  win- 
dow. View  the  information  by  pressing  |  clear  |  until  it 
appears.  When  you  no  longer  need  the  window,  use  DEINIZ 
to  remove  the  window  and  return  its  memory  to  the 
system. 

•  DEINIZ  performs  an  OS-9  I$Detach  call  for  all  specified 
devices. 


Example: 

To  deinitialize  the  /wl  (Window  1)  device  after  it  has  been  ini- 
deiniz  wl  |  ENTER | 


6-30 


System  Command  Descriptions  I  6 


DEL 


SftstBx:    del  [-x]  M&stmne  [...] 
Function:  Deletes  the  file(s)  specified. 

Parameter: 

filename  The  name  of  the  file  to  delete.  Include  as  many 

filenames  as  you  want. 

Option: 

-X  Causes  DEL  to  assume  the  file  is  in  the  cvir- 

rent  execution  directory. 

Notes: 

•  You  can  delete  only  files  for  which  you  have  write 

permission. 

You  can  delete  a  directory  in  two  ways:  (1)  Delete  all  the 
files  in  the  directory,  change  it  to  a  non-directory  file  using 
ATTR,  then  use  DEL  to  remove  the  directory,  or  (2)  Use  the 
DELDIR  command. 

•  The  fellowtng"  example  ^ows  what  appears  mi  the  sEeeen 
whm  you  display  a  directory,  delete  one  of  the  directory's 
files,  then  display  the  directory  again: 

dir   /d1  I  ENTER  | 

directory  of  /d1  14.29.46 
myfile  newflle 

del    newf  i  le  |  ENTER  | 
dir  /d1  I  ENTER  | 


direetory  of  /d1  14.30.37 
myfile 
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Esramples: 

•  lb  delete  files  named  TtecL-prpgram  and  Test—itt-Qgram, 
tjrpe: 

del    text  program  test  program  |  ENTER"| 

•  To  delete  a  file  on  a  drive  other  than  the  current  working 
drive,  use  a  complete  pathlist,  such  as: 

del  /d1 /number—five  [ENTERI 

•  To  d^ete  a  file  mamed  dmdksubdir  in      cmrmsii  mmm- 
tion  directory,  tj^pe: 

del  -X  cmd 5  .  5 u bd  1  f  flNTER  | 
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DELDIR 


Function:  Deletes  all  subdirectories  and  files  in  a  directory; 
then,  deletes  the  directory  itself. 


Parameter: 

dirname  The  pathlist  to  the  directory  you  want  to 

delete. 


Notes: 

•  DELDIR  is  a  convenient  alisesmsMm  to  in^vidually  dWettog 
all  the  files  and  subdirectories  from  a  directory  before 

deleting  the  directory  itself. 

•  When  DELDIR  runs,  it  displays  a  prompt  after  the  com- 
mand Une: 

deldir   oldf  i  les  |  ENTER  | 
Deleting  directory  file. 

List  directory,  delete  directory,  or  quit  ? 
Cl/d/q) 

Pressing  {T}  causes  a  DIR  E  command  to  run  so  you  can 
see  the  directory  files  before  DELDIR  removes  them. 

Pressing  (T)  starts  the  deletion  process. 

Pressing  [a]  cancels  the  command. 

•  The  directory  to  be  deleted  might  include  other  directories, 
which  in  turn  might  include  other  directories,  and  so  forth. 
In  this  case,  DELDIR  begins  with  the  lower  directories  and 
worki  its  upward. 

Y&a  must  have  write  permission  to  delete  any  flies  and 

directories  in  this  substructure.  If  not,  DELDIR  terminates 
when  it  encounters  the  first  file  for  which  you  don't  have 
write  permission. 
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•  DELDIR  automatically  calls  DIR  and  ATTR.  Therefore, 
these  files  must  reside  in  the  current  execution  directory. 
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DIR 

^mtax:     dir  [opIsiyiMaame  or  patbM$^ 

Function:  Displays  a  fomatted  list  of  filenames  in  a  directory, 
The  output  format  adjusts  itself  for  80-  or  32-column  displays. 

Parameters: 

dirname  The  name  of  the  directory  you  want  to  view. 

pathlist  The  pathlist  to  the  directory  you  want  to  view. 

opts  Either  or  both  of  the  following  options. 

Optioiis: 

ff  JOU  don't  specify  any  parameters,  DIR  shows  the  current 
dala  directory. 

X  Digflsps  the  current  execution  directory. 

e  Displays  the  entire  description  for  each  file: 

size,  address,  owner,  permissions,  date  and 
time  of  last  modification. 

Examples: 

•  To  display  the  currmt  data  directory,  type: 


dir  ENTER 


•  To  display  the  current  execution  directory,  type: 


dir    X  I  ENTER  | 


To  display  the  entire  description  of  all  files  in  the  current 
^ecution  directoi^^^  tj^pe: 


di  r  X  e  I  ENTER  I 
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•  Tq  display  the  parent  of  the  current  data  directory,  type: 

di  r    .  .  I  ENTER  | 

•  To  display  a  directory  named  NEWSTUFF,  type: 

dir   Tiewstuff  |  ENTER  | 

•  Following  is  a  sample  80-column  DIR  display  using  the  e 
option: 

dir   e  I  ENTER  | 

TkB  icreen  might  display: 

Directory  of    .  16i 51:12 

Dwrer  Last  modified  Attributes  Sector  Bytecount  Name 


2F   85/B5/2B  1631 

 wr 

3fi6C 

0S9Boot 

B   85/B5/2B  1345 

d- 

■ewrewr 

48 

642 

CMDS 

i   85/B5/2B  1358 

d- 

■ewrewr 

177 

M 

SYS 

I   85/e5/2«  1351 

•--r-wr 

192 

E 

startup 

i  85/05/28  1351 

d' 

■ewrewr 

19,4 

U 

DEFI 

•  fbllovvirig  is  an  80-column  HIR 11^^  ttfiag  no  ©ptims- 

d$r  mm\ 

The  screen  "miiht  dk^i^; 

Directory  of     .  16:50:37 


□S9Boot  CMDS  SYS  startup 
DEFS 
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•  Following  is  a  32-column  DIR  display  using  the  e  option: 

dir   e  |  ENTER  | 


Directory 

of 

.  16:52: 

104 

Modified 

mn 

Owner 

Attr 

Sector 

Size 

fic/cicr/oa 
oa /  10 3 /  CP 

1  CdQ 
1  J 

 wr 

A 

3  flee 

85/05/20 

1345 

0 

CMOS 

d-ewrewr 

48 

640 

85/05/20 

1  350 

0 

SYB 

d-ewrewr 

177 

fl0 

85/05/20 

T3H1 

0 

startup 

 r  -wr 

1  92 

E 

85/05/20 

1351 

0 

DEFS 

d-ewrewr 

194 

E0 

•  Ibltowing  is  a  32-column  TOR  display  using  w  options: 
dir  I  ENTEfl  I 

Directory  of      .  16:52:29 
DS9Boot         CMDS  SYS 
startup  DEFS 
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DISPLAY 

Syntax:    display  hex  [...] 

Function:  Reads  one  or  more  hexadecimal  numbers  (you  type 
as  parameters),  converts  them  to  ASCII  characters,  and 
writes  them  to  the  standard  output  (normally  the  screen). 

Parameters: 

h&c  A  list  of  one  or  more  heKadecimal  numbers. 

Notes: 

•  Use  DISPLAY  to  send  special  characters  (such  as  cursor 
and  screen  control  codes)  to  terminals  and  other  I/O 
devices. 

•  Mlowing  is  an  e&stmph  d  a  command  axid  ihe  fssulting 
output.  ABCDEF  are  ASCII  characters  corresponding  to 
hex  41  42  43  44  45  46. 

display  41    42  43  44  45  46  |  ENTER  | 
ABCDEF 

Examples: 

•  Tq  reroute  a  form  feed  (hex  OC)  to  th#  irtnter,  type: 

display  0C  >/p  |  ENTER  | 

•  Tb  ring  the  bdl  through  the  video  ^eaker^  type: 

display  07  |  ENTER  | 
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DSAVE 


Syntax:    dsave  [a^M[«^vname][dimame]  >  patblist 


Function:  Copies  or  backs  up  all  files  in  one  or  more 
directories. 


devname 

dirname 

pathlist 
opts 


The  drive  on  which  the  source  directory  exists. 
If  you  do  not  specify  devname  DSAIiTE  assumes 

Drive  /DO. 

The  name  of  the  destination  directory.  Use 
CHD  to  make  the  current  directory  the  direc- 
tory to  receive  the  copies. 

A  command  procedure  file  in  which  DSAVE 
stores  its  output. 

One  or  more  of  the  following  options. 


Options: 

-b 

-i 
-1 

-m 

-sinteger 


Makes  the  destination  or  target  diskette  a  sys- 
tem diskette  by  copying  the  source  diskette's 
OSSBoot  file,  if  present. 

Indents  for  directory  levels. 

Tells  DSi^iVE  not  to  process  direetcaies  bdow 
the  current  level, 

Tells  DSAVE  not  to  include  MAKDIR  com- 
mands in  the  procedure  file  it  creates. 

Sets  memory  for  the  copy  parameter  to  integer 
kilobytes. 

Wifies  copies  by  forking  to  CMP  after  copying 
each  file. 
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Notes: 

•  DSAVE  does  not  directly  affect  the  system.  Instead,  it  gen- 
erates a  procedure  file  that  you  execute  later  to  do  the 

•  When  you  mn  DSMD,  it  creates  a  procedtite  file  (a  file  dt 
commands).  You  then  execute  the  newly  created  file  by  typ- 
ing its  pathlist.  The  procedure  contains  all  the  commands 
to  create  and  change  directories  as  needed  in  order  to  copy 
the  specified  directory.  DSiW^E  copies  the  files  in  the  cur- 
rent data  directory.  It  also  copies  the  current  data  direc- 
tory subdirectories,  unless  you  specify  the  -1  option. 

•  To  use  DSAVE,  first  change  the  data  directory  to  the  direc- 
tory you  wish  to  copy.  Execute  DSAVE  by  specifying  the 
drive  fi:om  which  to  copy  and  then  redirecting  output  to  a 
file  to  receive  the  copy  commands.  Be  sure  to  name  a  file 
that  does  not  already  exist. 

When  mSWE  completes  the  procedure,  use  (SIID  to  ehange 
to  the  data  directory  to  receive  the  copied  files.  Then,  exe- 
cute the  procedure  file. 

•  If  DSAVE  encounters  a  directory  file,  it  automatically 
includes  MAKDIR  and  CHD  commands  in  the  output 

before  generating  COPY  commands  for  files  in  the  subdirec- 
tory. The  procedure  file  exactly  replicates  all  levels  of  the 
file  system  from  the  current  data  directory  downAward. 

•  If  the  current  data  directory  is  the  ROOT  directory  of  the 
disk,  DSAVE  creates  a  procedure  file  that  backs  up  the 
entire  disk  file  by  file.  This  is  useful  when  you  need  to  copy 
a  number  of  files  from  either  disks  formatted  differently  or 
from  floppy  diskettes  to  a  hard  disk. 

•  In  the  following  series  of  commands,  CHD  positions  you  in 
the  ROOT  directory  of  ITM,  the  directory  to  be  copied. 

Then,  DSAVE  makes  the  procedure  file  Makecopy.  Using 
CHD  /Dl  causes  the  copy  to  go  in  the  /Dl  ROOT  directory. 
The  final  command  sEecutes  the  procedure  file. 
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dsave  /d2  > /d0 /mak  ec opy  |  ENTER  | 
chd    /d1  I  ENTER  | 
/d0/makecopy  |  ENTER  | 

•  The  following  command  copies  all  files  from  /DO  to  /Dl.  It 
pipes  the  procedure  file  ootput  of  DSAVE  into  a  diell  for 
immediate  execution. 

dsave      /d0      /dl      !      shell  [InTERI 

•  The  following  command  lets  you  view  the  output  generated 
by  a  DSAVE  command.  It  uses  48  kilobytes  of  memory  and 
indents  directories.  Because  output  goes  to  the  screen,  this 
command  does  not  create  a  procediure  file  to  copy  any  files: 

dsave    -s48   -i  |  ENTER  | 

•  This  command  operates  in  the  same  manner  as  the  pre- 
vious command.  Howevca!',  because  it  specifies  a  pro^dure 
file  pathlist,  it  stores  the  generated  commands  in  a  proce- 
dure file  rather  than  displaying  them  on  the  screen: 

dsave   -548   -i    >   copyf  i  le  |  ENTER  | 
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ECHO 


Syntax:    echo  text 

Function:  Echoes  text  to  the  screen. 


Parameters: 

text  The  character  or  characters  you  type. 

Notes: 

•  T3m  ECHO  ^  generate  messages  lit  shell  procedure  files  or 
to  send  an  initialization  character  sequence  to  a  terminal. 
The  text  should  not  include  punctuation  characters  used  by 
1^  shell. 

•  The  following  example  prints  the  message  LISTING  ERROR 
MESSAGES  to  the  screen  and  lists  the  file  SYS/errmsg  to  the 
pdntm  m  a  Mkgeooiid  tai^. 

echo  LISTING  ERROR  MESSftGES;  list  ays/ 
errmsg  >/p*  I  ENTER  I 

Examples: 

•  To  display  a  message  on  the  screen,  tj^e: 

echo  This   text   ia  echoing  I  ENTER  | 

•  To  echo  text  to  the  console,  type: 

echo  >/term  ••WARNING  DATA  DN  DISK  WILL  BE 
LOST  I  ENTER  I 

•  The  Mlmixsg  comMnes  the  ECHO  and  IlgT  (^nauEmds  to 
echo  the  entered  text  to  the  printer  and  to  direct  the  con- 
tents of  the  Trans  file  to  the  printer. 

echo  >/p  LISTING  OF  TRANSACTION;  list  trans 
>/p*  I  ENTER  I 
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ERROR 


Slyntax:     error  errnumber  [...] 

Function:  Displays  the  text  error  message  that  coirespcmds 
with  the  specified  OS-9  error  number. 

errnumber       fe  an  OS-9  error  code  in  the  range  1-255. 
Notes: 

•  ERROR  opens  the  Errmsg  file  in  the  SYS  directory  and 
reads  through  the  file  for  an  error  code  that  matches  the 
specified  number.  It  then  displays  the  text  that  corresponds 

to  the  error  code. 

•  The  Errmsg  file  contains  descriptions  of  the  standard  OS-9 
errors.  The  order  of  the  file  is  arranged  to  provide  quick 
access  to  operation  system  error  descriptions. 

Example: 

•  To  display  a  description  of  the  OS-9     or  Numbers  215  and 

216,  type: 

error   215   216  |  ENTER  | 
The  screen  displays: 

215  -  Bad  Path  Name 

216  -  Path  Name  Not  Found 
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EX 


%iitax:    ex  Memmhe 

Fimctkm:  Starts  a  process  by  cJminir^  froin  the  cupreiit  shell 
to  liie  proiMsa  Chaining  rasEtns  liat  esetaiMcaa  control  fs 
turned  over  to  the  new  process. 

Parameters: 

filemrm  The  name  of  the  program  or  module  you  want 

to  execute. 

Notes: 

•  Because  EX  is  a  built  in  Shell  command,  it  does  not  appear 
in  the  CMDS  directory. 

•  Using  EX  causes  the  shell  from  which  you  are  operating  to 
terminate.  If  the  new  process  also  terminates  and  you  do 
not  have  another  shell  running  on  another  terminal  or  win- 
dow, OS-9  is  left  without  any  processes,  and  you  must 
reboot  your  computer  and  OS-9. 

•  If  a  shell  is  running  on  another  window  or  device,  you  can 
restart  a  new  shell  from  that  window  or  device.  For 
instance,  if  you  use  EX  to  initialize  BAS1C09  from  /TERM 
then  exit  BASIC09,  /TERM  is  dead  and  cannot  accept  key- 
board input.  However,  if  you  also  have  a  shell  operating  in 
a  window,  you  can  tjrpe  the  following  from  that  window. 

shell   l  =  /termt  TENTER | 

This  reinitializes  a  shell  on  /TERM.  It  can  now  accept  key- 
board input  and  OS-9  commands. 

•  Use  EX  to  save  memory  when  the  shell  is  not  needed,  for 
instance  when  using  BASIC09. 
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•  If  you  use  EX  on  a  command  line  with  other  commands,  it 
must  be  the  last  command.  Any  eommands  following  EX 
are  not  processed. 

Example: 

•  Tb  run  BASIC09  without  a  resident  shell,  type; 

ex  ba5lc09  flNTlRl 
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FORMAT 


^^tax:    format  devmamB  Immm]  [opts] 

Function:  Establishes  sod  vedfiies  an  initial  file  structure  on 
a  floppy  ^E^sette  OF  a  Iiard  di^.  ISni  must  finrmat  all  di^ 
b^ore  you  can  use  tfaem  on  an  08-9  system. 


Parameters: 

devname 

name 

opts 
Opiicms: 


The  drive  name  of  the  disk  you  want  to 
format. 

The  name  you  'vmnt  to  asiipi  lh@  fbr- 
matted  disk.  Enclose  the  didk  name  in  double 

quotation  marks. 

One  or  more  of  the  following  options. 


1  VMtes  system  format  infbmation  only,  does 

not  physically  format  disk. 

r  Causes  the  format  to  proceed  automatically, 

without  issuing  prompts. 

1  Formats  single-sided.  Use  with  single-sided 
drives  or  single-sided  diskettes  in  double-sided 
drives. 

2  Causes  a  double-sided  format.  Use  with 
double-sided  drives  and  double-sided  diskettes. 

'^mders'  The  number  of  (flinders  (in  decimal)  that  ywu 
want  formatted. 

'.interleave:  The  number  of  the  sector  interleave  value  (in 
decimal). 
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Notes; 

•  Be  SUte  the  disk  you  want  to  format  is  NOT  write- 
protected.  Otherwise,  FORMAT  generates  error  code  #242 
(write  protect),  sind  the  system  returns  to  the  OS-9  prompt 
without  formatting  the  didtette. 

•  If  you  are  formatting  a  hard  disk,  first 

tmode  -pause  |  ENTER | 

This  command  turns  off  the  screen  pause  function.  Other- 
wise, the  process  stops  whenever  the  sector  verification  pro- 
cess fills  the  display  screen.  If  you  forget  to  turn  off  the 
screen  pause,  press  the  space  bar  whenever  the  screen  fills. 
Execution  then  continues. 

When  formatting  finishes,  type: 

tmode   pause  |  ENTER  | 

This  re-establishes  the  screen  pause  function. 

•  The  formatting  process  works  this  way: 

1.  FORMAT  physically  initializes  a  disk  and  divides 
its  surface  into  sectors. 

2.  FORMAT  reads  back  and  verifies  each  sector.  If  a 
sector  fails  to  verify  after  several  attempts,  FOR- 
MAT axcludes  it  from  the  initial  free  space  on  the 
diskette.  As  verification  proceeds,  the  process  dis- 
plays track  numbers. 

3.  FORMAT  writes  the  disk  allocation  map,  ROOT 
directory,  and  identification  sector  to  the  first  few 
sectors  of  Track  0.  These  sectors  must  not  be 
defective. 

•  FORMAT  asks  for  a  disfe  veluine  natue,  which  can  be  up  to 

32  characters  long  and  can  include  spaces  or  punctuation. 
(Later,  you  can  use  the  FREE  command  to  display  the 
name.) 
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•  For  step-by-step  instructions  on  formatting,  refer  to  Getting 
Started  With  08-9. 

Examples: 

•  Tb  format  a  diskette  in  Drive  /Dl,  type: 

f  ormat   /dl  |  ENTER  | 

•  To  format  a  diskette  in  Drive  /Dl  with  the  name  Test  Disk 
and  without  prompts,  type: 

format    /dl    r   "test   disk"!  ENTER  | 

•  To  format  hard  Disk  /HO,  type: 

tmode  -pat* He  |  ENTER  | 
format   /h0  ||tnil[ 
tmode  pause  IfifBBi 

•  To  format  a  double-sided  diskette  in  Diive  /D2  with  27  cyl- 
inders and  the  name  Database,  type: 

format   /dl    2  "database"   '27'  |  ENTER  | 
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FREE 


Syntax:     free  [devname] 

Function:  Displays  the  number  of  unused  sectors  (256-byte 
storage  areas)  on  a  disk  drive.  These  sectors  are  ava41aMel& 
new  files  or  for  expanding  existing  files. 

Parameters: 

devname  The  disk  drive  for  which  you  want  to  display 

the  number  of  free  sectors. 

Notes: 

•  The  device  name  you  specify  must  be  a  disk  drive.  FREE 
also  displays  the  disk's  name,  creation  date,  and  cluster 
size.  If  you  don't  specify  a  drive,  FREE  selects  the  drive 
that  contains  the  current  data  directory. 

•  The  cluster  size  for  the  Color  Computer  is  one  sector. 
Examples: 

•  To  display  the  number  of  free  sectors  on  the  current  disk, 
type: 

free  |  ENTER  | 

The  screen  is  similar  to  this: 

"COLOR  COMPUTER  DISK"  created  on:  83/05/28 

Capacity:  G30  sectors  Cl-sector  clusters) 
15   Free   sectors,    largest   block    12  sectors 

•  To  display  the  number  of  free  sectors  on  the  diskette  in 
Drive  /Dl,  type: 

f  ree  /dl  |  EHTER  | 
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A  sample  screen  display  is: 

"DATA  DISK"  created  on:  83/06/16 
Capacity:  ©IB  seel or a  Cl-seetor  clusters^ 
44S  Free  sectors,  largest  block  442  sectors 
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HELP 


Syntax:    help  [command  name]  [-?] 

Function:  Displays  the  use  and  syntaxes  of  OS-9  commands. 

Paramet^si 

command  The  command(s)  for  which  you  want  help. 

name  Include  as  many  command  names  as  you  want. 

-?  Gives  a  list  of  hdp  topics. 

Notes: 

•  HELP  uses  a  file  named  Helpmsg,  which  is  located  in  the 
SYS  directory  on  your  systaa  diskette. 

Examples: 

•  To  obtain  help  for  the  BACKUP  command,  type: 

help   backup  |  ENTER  | 

The  screen  displays: 

Syntax:    backup    [ e ] [ s ] C -v ] [ dev ] [ dev ] 

Usage:    Copies   aH   data   from  one  device  to 

another 

•  If  you  try  to  obtain  help  for  a  non-existent  command,  HELP 
displays  an  error  mesmge.  Ibr  instance,  if  you  type: 

help  me  |  ENTER  | 

me:   no  help  available 

•  YovL  can  also  obtain  help  for  the  HELP  cotnmanid.  lb  do  bo, 
type: 

help   help  |  ENTER  | 

The  screen  displays: 

Syntax:   Help   [ sub j ect It -? I 
Usage:   Give  on-line  help   to  users 

Will  prompt   if  no  subjects  given 
Dpts:   -?  give  list  of  help  topics 
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IDENT 


%iitax:    ident  Glemam  i&pts§ 


Functioa:  Displays  header  information  &r  memory  modules. 


Parameters: 

filename  The  name  of  the  file  or  module  for  which  you 

want  to  view  identification  information. 

opts  One  or  more  c£  the  following  options. 


Options: 

-m  Causes  IDENT  to  assume  that  filename  is  a 

module  in  memory 

-V  Tdls  IDENT  not  to  vraify  module  cyclic  redtm- 

dancy  check 

-X  Causes  IDENT  to  assume  that  filename  is  in 

the  execution  directory 

-s  Displays  the  following  module  information  on  a 

single  line:  the  edition  bj^e  (first  byte  after 
module  name),  the  type/language  byte,  the 
module  CRC  and  the  module  name.  A  period 
(.)  indicates  that  the  CRC  verifies.  A  question 
mark  (?)  indicates  that  the  CRC  does  not 
verify. 


Notes: 


•  IDENT  displays  the  module  size,  CRC  bjrtes  (with  verifica- 
tion), and — ^for  program  and  device  driver  modules — ^the  ejce- 
cution  offset  and  the  permanent  storage  requirement  bytes. 
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•  IDENT  displays  and  interprets  the  type/language  and 
attribute  revision  bytes.  IDENT  displays  the  byte  immedi- 
ately following  the-  flap&le  name  because  most  Microware®- 
supplied  modules  Set  this  byte  to  indicate  the  module 
edition. 

•  IDENT  displays  all  modules  contained  in  a  disk  file. 
Examples: 

•  To  display  header  information  for  a  file  named  Bent  that 
resides  in  computer  memory,  type: 

ident   -m  ident  |  ENTER  | 

The  screen  might  display: 

Header   for:  IDENT 
Module   5ize:$06E7  #1767 

Module  CRC:    $540312  tGood) 
Hdr  parity:  $C9 

Exec,   off:     $0230  #B73 
Data  Size:      $099C  #2460 
Edition:  $07  #7 

Ty/La   At/Rv:$11  $81 

Prog  mod,   6809  obj  ,  re-en,  R/0 

In  the  example,  Hdr  parity  =  header  parity;  Exec,  off  = 
execution  offset;  Data  size  =  permanent  storage  require- 
ments; Edition  =  first  byte  after  module  name;  Ty/La  At/ 
Rv  =  type/language  attribute/revision;  and  Prog  mod, 
6809  obj,  re-en  =  module  type,  language,  attribute. 

•  To  display  header  information  for  the  OS9Boot  file,t^e: 

ident  /D0/OS9boot  -s  I  ENTER  | 
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The  display  might  include: 


1  7 

$C0 

$F2922F  . 

.  QS9p2 

©•? 

$60 

$082322  , 

,  ItTit 

1  2 

$C1 

$2E9EDB  , 

,  IQMan 

27 

$D1 

$B6e5E3  , 

,  RBF 

6 

$E1 

$055580  , 

,  CC3Disk 

82 

$F1 

$FC1918  , 

.  D0 

82 

$F1 

#9F4210  , 

,  D1 

82 

$F1 

$EeB118  , 

,  DD 

1  1 

$D1 

$10A3FA  , 

,  SCF 

1  4 

$E1 

$8524F1  , 

,  CC3ID 

1 

$C1 

$B53D94  , 

,  VDGInt 

3 

*C1 

$792B7E  , 

.  Grflnt 

83 

$F1 

$AB5AE5  , 

,  TERM 

83 

$F1 

$7AB2DB  , 

,  N 

83 

$F1 

$C3E38A  , 

,  N1 

83 

$F1 

$948878  . 

,  W2 

83 

iFT 

$380168  , 

.  'W3 

83 

$F1 

$0AE2Be  , 

,  W4 

83 

$F1 

$123B9A  , 

.  N5 

IF1 

$1CF1®4  , 

.  m 

83 

$F1 

$B71DF5  , 

.  W7 

1 1 

$E1 

$C8F073  , 

.  ACIAPAK 

82 

$F1 

$9E655D  , 

.  T2 

1  2 

$E1 

$CC3EA4  , 

,  PRINTER 

83 

$P1 

wwwmi.  : 

.  ¥ 

4 

$D1 

$AD6718  , 

.  PipeMan 

2 

$E1 

$5B2B56 

.  Piper 

80 

$F1 

$CC06AF 

.  Pipe 

9 

$C1 

$BE93F4  , 

.  Clock 

3 

$11 

$Cft1F99  . 

Since  the  -s  option  app€^s  m  ths  eosoMand  line,  IDENT 
displays  each  module's  information  on  a  single  line.  In  the 
first  line  of  the  output,  for  instance,  17  =  edition  byte 
(first  byte  after  name),  $C0  =  type/language  byte, 
$A366DC  =  CRC  value,  .  =  OK  CRC  check,  and  OS9p2  = 
module  name. 
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INIZ 


Sjrntax:    iniz  devname  [...] 


Function:  Initializes  the  specified  device  driver, 


Parameters: 

devname  The  name  of  one  or  more  devices  to  initialize. 


Notes: 

•  You  can  use  INIZ  in  the  Startup  file  or  at  the  system  start- 
up to  initialize  devices  and  allocate  their  static  storage  at 
the  top  of  memory  to  reduce  memory  fragmentation. 

•  INIZ  attaches  the  specified  device  to  OS-9,  places  the  device 
address  in  a  new  device  table  entry,  allocates  the  memory 
needed  by  the  device  driver,  and  calls  the  device  driver  ini- 
tialization routine.  INIZ  does  not  reinitialize  a  device  that 

you  or  the  system  previously  installed. 

•  If  you  change  the  printer  (/p)  to  a  non-shareable  device  (a 
device  that  is  not  re-entrant),  do  not  initialize  it  vdth  INIZ. 


Examples: 

•  To  initialize  the  /P  (printer)  and  /T2  (terminal  2)  devices, 
type: 

iniz  p  t  2  I  ENTER  | 
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KILL 


Syntax:    kill  procID 

Functloii:  Ita^nates  the  process  specified  by  prodD. 

Parameters: 

procID  The  ID  number  of  the  process  to  kill. 

Notes: 

•  Unless  you  are  the  Super  User  (User  Number  0),  you  can 
only  terminate  a  process  that  has  your  user  number.  (Use 
PROCS  to  obtain  the  process  ID  numbers.)  The  Super  User 

can  terminate  any  process. 

•  If  a  process  is  waiting  for  I/O,  you  cannot  cancel  it  until  the 
current  PO  eperatitm  termhiates.  Thfirrfore,  !f  fea  KJXiL  a 
process  and  PROCS  shows  it  still  exists,  it  is  probably  wait- 
ing to  receive  a  line  of  data  from  a  terminal. 

•  Because  KILL  is  a  built-in  shell  command,  it  does  not 
appear  in  the  GMDS  directory. 

Examples: 

•  Tb  MILL  the  process  with  the  ID  number  5,  type: 

kill  e  IBmBI 

•  The  following  commands:  (1)  use  PROCS  to  deterifiine  that 

the  ID  number  of  the  process  to  be  killed  is  3,  (2)  termi- 
nate process  3,  and  (3)  use  PROCS  to  confirm  that  KILL 
has  cancelled  the  process. 
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procs  I  ENTER  | 


Mpdi  ^ t ar t 

1  1  Clll    J  L  U  U  h 

Id 

Pld  Number 

Pty  flge  Sts 

Signl  Siz    Ptr     Primary  Module 

2 

1  0 

1 £0    1 £0  fOD 

3 

5  t 

128  128  m 

8      2  t74flC  Tsmoii 

5  ! 

128  128  m 

8      B  $85F3  Procs 

5 

i  t 

128  129  t8e 

8      3  $6FE2  Shell 

hi 

3  1  ENTER  1 

procs  i  ENTER  | 

User 

Mem  Stack 

Id 

Pld  Number 

Pty  flge  Sts  Signl  Siz   Ptr     Pi-imafy  Module 

2 

1  I 

128  128  $88 

8      3  $7882  Shell 

3 

5  t 

128  128  $88 

8      e  $B5F3  Procs 

5 

i  i 

128  123  $88 

8      3  $6FE2  Shell 
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LINK 

%iitax:    link  modname 

Function:  Locks  a  previously  baded  module  iiito  memory. 

Parameters: 

modname        The  iiame  of  the  memory  module  to  link. 

Notes: 

•  If  the  module  is  not  already  in  memory,  you  must  use 
LOAD  prior  to  using  LINK.  The  link  count  of  the  module 
increases  by  one  each  time  the  system  links  it.  Use 
UNLINK  to  unlock  the  module  when  you  no  longear  need  it. 

Examples: 

•  To  lock  the  Edit  module  into  memory,  type: 

link  edit  |  ENTER  | 
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LIST 


Syntax:    Ust  M&mme  [...] 


Function:  Lasts  the  cont^ts  of  a  text  file  or  files. 


Parameters: 

filmame  The  name  of  the  file  you  want  to  list.  Include 

as  many  filenames  on  one  line  as  you  want,  up 
to  the  maxiinuin  line  lerigth  of  199  characters. 

Notes: 

•  LIST  copies  t^  lines  from  a  file  to  the  standard  oatfHlt 

path.  The  program  terminates  upon  reaching  the  end-of-file 
of  the  last  input  path.  If  you  specify  more  than  one  file, 
LIST  copies  the  files  in  the  order  la  which  you  list  them. 

•  Use  LIST  to  examine  or  print  text  files. 

•  Do  not  LIST  executable  files.  Doing  so  can  cause  your  sys- 
tem to  lock  or  crash.  To  view  executable  files,  use  DUMP. 


Examples: 

•  To  list  the  contents  of  the  Startup  file  to  the  printer,  tj^e: 

list  /d0/ataptup  >/p&  I  ENTER  I 

The  ampersand  makes  the  printing  job  a  concurrently  exe- 
cuted task. 

•  To  list  three  files  to  the  screen,  type: 

list  /  d  1  /  u  5  e  r  5  /  d  o  c  lime  n  t  /d0/myfile  /d0/ 
bob/text  I  ENTER  | 

•  To  copy  everjiiung  you  type  at  the  k^board  to  the  printer, 

type: 

list   /term  >/p  I  ENTER  I 
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To  go  back  to  the  standard  output  path  (the  video  display) 
press  I  CTRL  II  break]. 

•  The  following  commands  create  a  file  called  Animals,  con- 
sisting of  six  entries.  LIST,  with  the  filename  Animals  as  a 
parameter,  displays  the  contents  of  the  new  file. 

build  animals  |  ENTER  j 

?  cat  I  ENTER  | 

?    cow  I  ENTER  I 

?    dog  I  ENTER  | 

?   elephant  |  ENTER  I 

?  bird  I  ENTER  | 

t  f  tsh  I  ENTER  I 

?  I  BITER  I 

Hat  animals  |  ENTER  I 

The  screen  displays: 

eel 
cow 
dog 

e  1  ephant 

bird 

fish 
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LOAD 


Spitax;    load  patbUst 

Function:  Loads  a  module  (program)  from  a  file  into  memoiy. 

Parameters: 

pathlist  Specifies  the  module  to  load. 

Notes: 

•  LOAD  opens  the  path  you  specify,  then  loads  into  memory 
one  or  more  modules  from  it.  The  process  adds  the  names  of 
the  new  modules  to  the  module  directory.  If  LOAD  finds 
that  a  specified  module  has  the  same  name  and  type  as  a 
module  already  in  memory,  it  keeps  the  module  with  the 
highest  revision  level. 

•  If  the  pathlist  for  LOAD  does  not  include  a  drive  name, 
LOAD  uses  the  current  execution  directory.  To  LOAD  a 
module  from  a  directory  other  than  the  current  execution 
directory,  specify  a  full  pathlist,  beginning  with  a  drive 
name  if  applicable. 

Examples: 

•  In  the  following  example,  MDIR  displays  the  names  of  mod- 
ules currently  resident  in  memory.  Then,  LOAD  loads  the 
Edit  module  into  memory.  MDIR  again  lists  memory  mod- 
ules, and  this  time  shows  that  Edit  is  successfully  added  to 
memory. 

mdir  |  ENTER ) 
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The  soreen  display  is  similar  to  the  following: 


Module 

Directory 

at  12:49 

:52 
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H0 

Shell 

Copy 

Date 

Delniz 
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Dir 
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Echo 

Iniz 

Link 
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Load 

MDlr 
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Mf  ree 
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Set  ime 
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Grf Drv 

load  edit  flfilil 
mdir  I  ENTER  I 

The  screen  displ^: 

Module  Directory  at  12:S1:12 
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MAKDIR 

Syntax:    makdir  patblist  or  dimame 

Function:  Creates  a  directory  according  to  the  pathlist  given. 
You  must  have  write  permission  for  the  parent  directory  of  the 
directory  you  are  creatii^. 

FarameteFs: 

pathlist  The  path  to  the  directory  you  want  to  create. 

dimame         The  name  of  the  directory  you  want  to  create. 

Notes: 

•  When  MAKDIR  initializes  the  new  directory,  the  directory 

contains  only  the  "."  and  files. 

•  MAKDIR  enables  all  permissions  for  the  directory  it 
creates. 

•  To  follow  OS-f  convention,  capitalize  all  directory  namtes. 
Examples: 

•  To  create  a  directory  on  Drive  /Dl,  use  the  directory's  full 
pathlist  from  the  root,  such  as: 

makdir  /dl  /STEVE/PRDJECT  |  ENTER  I 

•  To  create  a  directory  called  DATAFILES  within  the  current 
data  directory,  type: 

makdir   DftTflFILES  |  ENTER  | 

•  To  create  a  directory  called  SAVEFILES  in  the  parent  of 
the  cvirrent  directory,  type: 

miskdir   .  .  /SftVEF  I LES  UnterI 
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MDIR 


^ntax:    mdir  [e] 

Function:  Displays  the  names  of  modules  currently  in  mem- 
ory. MDIR  automatically  adjusts  its  output  for  32-  or  80- 
column  displays. 

Options: 

e  Causes  a  fall  listing  of  the  extended  physical 

address  (block  number  and  offset  within  the 
block),  size,  type,  revision  level,  re-entrant 
attribute,  user  count,  and  name  of  each  mod- 
ille.  MDIR  shows  numbers  in  hexadecimal. 
*Sbm  display  adjusts  for  i80  or  32  columns. 

Notes: 

•  Many  of  the  modules  displayed  by  MDIR  are  OS-9  system 
modules  and  are  not  executable  as  programs.  Always 
check  the  module  type  code  before  running  a  module 
with  which  you  are  not  familiar. 

Examples: 

•  Because  MDIR  adjusts  to  either  32  or  80  columns,  the  fol- 
lowing ccnnmand  produces  a  full  module  listing  in  either 
format: 

mdir   e  |  ENTER  | 
The  80-column  display  of  MDIR  e  is: 
Module  Directory  at  IS3!B3;53 

Sliiti  Of  tst't  iim  ff p  te?  'ttlf   lite  ladtlia  Msm. 

3F       m     12A    C1      1  r...       0  REL 
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0  0elniz 

6 

fl41 

AS 

11 

1 

r . . . 

0  Del 

6 

Are 

36S 

11 

1 

r. . . 

0  Dir 

6 

E4B 

84 

11 

1 

r .  .  . 

0  Display 

6 

ECF 

22 

11 

1 

r . . . 

0  Echo 

i 

EF1 

SA 

11 

1 

f . . . 

0  Inlz 

6 

m 

26 

11 

1 

r,». 

0  ynfc 

6 

F87 

4F 

11 

1 

r. . . 

0  List 

6 

FDG 

24 

11 

1 

r . . . 

0  Load 

6 

FFA 

2F1 

11 

1 

r . . . 

1  MDir 
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6 

12EB 

68 

11 

1  r.  .  . 

0  Merge 

e 

1353 

1EB 

11 

1  r. .  . 

0  Mfree 

6 

1S3E 

319 

11 

1  r... 

0  Proca 

6 

1857 

11D 

11 

1  r... 

0  Rename 

6 

1974 

118 

11 

1  r... 

?  Setime 

6 

1A8C 

381 

11 

1  r. . . 

0  Tmode 

G 

1D8D 

2D 

1 1 

1  r. .  . 

0  Unlink 

•  The  32-column  display  of  MDIR  is: 

Module  Directory  at  03:06:49 


Blk  Ofst  Size  Ty  Rv  At  Uc  Name 


3F 

D06 

1  2A 

C 1 

1  r 

0 

REL 

3F 

E30 

1  D0 

CI 

1  r 

1 

Boot 

3F 

1 0f 

ED9 

00 

8  r 

0 

0S9p1 

1 

20  0 

CA1 

C0 

2  r 

1 

□  S9p2 

1 

E  A 1 

2E 

C0 

1  r 

1 

I  n  i  t 

1 

ECF 

993 

C 1 

1  r 

1 

I  QMan 

1 

1  862 

1  22B 

D1 

1  r 

70 

RBF 

1 

2ft8D 

47G 

El 

1  r 

2 

CC3Disk 

1 

2F03 

30 

F1 

1  r 

2 

D0 

1 

2F33 

30 

F1 

1  r 

0 

Dl 

1 

2F63 

30 

F1 

1  r 

0 

DD 

1 

2F93 

5B6 

Dl 

1  r 

24 

SCF 

1 

3549 

B91 

El 

1  r 

D 

cc3ia 

1 

40DA 

CE7 

CI 

1  r 

1 

VDGI nt 

1 

4DC1 

BF2 

CI 

1  r 

1 

Grf Int 

1 

59B3 

45 

Fl 

1  r 

8 

TERM 

1 

S9F8 

43 

F1 

1  r 

0 

M 

1 

5fi3fi 

43 

Fl 

1  r 

0 

M1 

1 

5A7D 

43 

Fl 

1  r 

0 

W2 

1 

5AC0 

43 

Fl 

1  r 

0 

N3 

1 

5B03 

43 

Fl 

1  r 

0 

W4 

1 

5B46 

43 

Fl 

1  P 

0 

145 

1 

SB89 

43 

F1 

1  r 

0 

M6 

1 

5BCC 

43 

Fl 

1  r 

5 

W7 

1 

5C0F 

3B5 

El 

1  r 

A 

ACIAPAK 

1 

5FC4 

W 

Fl 

1  r 

B 

T2 

1 

6003 

MPi 

El 

1  r 

D 

PRINTER 

1 

61  7D 

3C 

Fl 

1  r 

D 

P 

1 

61  09 

219 

Dl 

1  r 

1  2 

P  i  peMan 

1 

G3D2 

28 

El 

1  r 

1  2 

Piper 

1 

63FA 

26 

Fl 

1  r 

12 

Pipe 

1 

64  2  Q 

174 

CI 

1  r 

1 

Clock 
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1 

6594 

1  AA 

1 1 

1 

CC3Go 

6 

0 

5F2 

1 1 

1  r 

3 

Shell 

6 

5F2 

2DC 

1  1 

1  r 

a 

Copy 

6 

8CE 

FD 

1  1 

1  r 

a 

Date 

6 

9CB 

76 

1  1 

1  r 

DEIniz 

6 

A41 

A5 

1 1 

1  r 

0 

Del 

6 

AE6 

365 

1 1 

1  r 

0 

Dip 

6 

E4B 

84 

1 1 

1  r 

B 

D  i  s  D 1 av 

6 

ECF 

22 

1 1 

1  r 

e 

Echo 

6 

EF1 

6A 

1 1 

1  r 

e 

I  n  i  z 

6 

FSB 

2C 

1 1 

1  r 

0 

Link 

6 

FS7 

4F 

1 1 

1  r 

0 

Li5t 

6 

FDG 

24 

1  1 

1  r 

0 

Load 

6 

FFA 

2F1 

1  1 

1  r 

1 

MDir 

e 

12EB 

68 

1 1 

1  r 

Mfir  de 

6 

1353 

1EB 

11 

1  F 

a 

Mf  i*ee 

6 

1S3E 

319 

1 1 

1  r 

0 

Procs 

6 

1  857 

1  1  D 

1  1 

1  r 

0 

Rename 

6 

1974 

118 

1  1 

1  r 

0 

Set Ime 

6 

1A8C 

301 

1 1 

1  r 

0 

Tmode 

6 

1D8D 

2D 

1 1 

1  R 

0 

UnliTifc 
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MERGE 


^mtax:    merge  [SIename][...] 

Function:  Copies  files  to  the  standard  output  path.  By  redi- 
jee0&ng  the  output  of  the  MERGE  command,  you  can  combine 
several  files  into  one  file,  or  direct  several  files  to  the  printer. 

Parameters: 

filename  Specifies  the  files  to  combine. 

Notes: 

•  Use  MERGE  to  combine  se^al  fili^  loto  a  single  output 
file.  It  copies  data  in  the  order  in  vMcii  you  type  the 

filenames. 

•  MERGE  does  not  output  line  editing  characters  (such  as 
the  automatic  line  feed). 

•  You  normally  use  MERGE  with  tiie  standard  oulput  redi- 
rected to  a  file  or  device. 

•  '^5>u  can  use  MERGE  to  append  or  cpgy  any  type  or  mix- 
ture of  files  to  another  device. 

Examples: 

•  Tb  merge  four  files  into  a  new  file  called  Combined.file,  and 
send  the  results  to  the  new  file  instead  of  to  the  video  dis- 
play, type: 

merge  flle1  fileZ  fUe3  file4  >combiiied.f ile 
1  ENTER  I 

•  lb  merge  two  files,  and  send  the  output  to  the  printer,  type: 

merge  compile. list  asm. list  >/P  | ENTER] 
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MFREE 


^mtax:  mfree 

Function:  Displays  a  list  of  memory  areas  not  present^y  in  use 
and,  therefore,  available  for  assignment. 

Notes: 

•  MFREE  displays  the  block  number,  physical  (extended) 
beginning  and  ending  addresses,  and  the  size  of  each  con- 
tiguous area  of  unassigned  RAM.  It  gives  the  size  in  num- 
ber of  blocks  and  in  kilobytes.  The  block  size  is  8  kilobytes 
per  Mock.  Free  memory  for  user  data  samm  ^ms  mt  need  to 
be  contiguous  because  the  MMU  can  ma,p  scattered  free 
blocks  to  be  logically  contiguous. 

Examples: 

•  Type  this  command: 

mfree  |  ENTER  | 
The  screen  shows  a  display  similar  to  this: 
Blk  Begin     End     Blks  Size 


10  12000  10FFF 
18  18000  1DFFF 
20     20000  3FFFF 

Total : 


1  8K 

3  24K 

16  \mK 

20  160 
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MODPATCH 


Syntax:    modpatch  [e^pMems]  fflename  [epMons] 


Function:  modifies  modules  residing  in  memory.  MODPATCH 
tm$$  &  poMhf^  sB^  esQscutes  the  commands  in  the  patchfile 
to  change  the  contmts  d  one  or  more  modules. 


Parameters: 

filename 

options 
Options: 


-w 
-c 


The  name  of  a  file  containing  instructions  for 
MODPATCH 

One  of  the  following  options  that  change  MOD- 
PATCH's  function 


Silent  mode,  does  not  display  patchfile  com- 
mand Hnes  as  th^  are  eicecuted. 

Does  not  displs^  'warnings,  if  ai^ 

Ccnnpares  onOLy,  does  not  chan^  tiie  module 
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Notes: 


•  Before  using  MODPATCH,  you  must  create  a  patchfile  to 
supply  the  data  to  control  MODPATCH's  operation.  This  file 
contains  single-letter  commands  and  the  appropriate  mod- 
ule addresses.  The  commands  axe: 


I  rmdulmanie 

G  ofl^et  origval  mmal 

V 

m 


Link      &@  module  specified 

Change  the  byte  at  the  offset 
address  specified  by  offset  from 
the  value  specified  by  origval 
to  the  new  value  specified  by 
rmwmd.  If  the  original  Talus 
does  not  match  origval,  MOD- 
PATCH  displays  a  message. 

Verify  the  module — update  the 
modules  CRC.  If  you  plan  to 
save  the  patched  module  to  a 
file  that  the  system  can  load, 
you  must  use  this  command. 

Mask  IRQ's.  Turns  off  inter- 
rupt requests  (for  patching 
service  routines). 

Unmask  IRQ's.  Turns  on  inter- 
rupt requests  (for  patching 
service  routines). 


•  You  can  use  the  BUILD  command  or  any  word  processing 
program  to  create  patchfiles. 

•  Module  byte  addresses  begin  at  0.  MODPATCH  changes 
values  pointed  to  by  an  offset  address  (offset  from  0)  rather 
than  an  absolute  memory  address. 
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•  To  view  the  contents  of  a  memory  module,  use  SjfWE  and 
DUMP  to  copy  the  module  to  a  file  and  display  its  contents. 
Also  use;         to  copy  the  patched  module  to  a  disk  file. 

•  Changing  a  memory  module  might  not  produce  an  immedi- 
ate effect.  You  have  to  duplicate  the  initialization  procedure 
fbi»  that  module.  This  means,  if  the  module  loads  during 

bootup,  you  have  to  create  a  new  boot  file  that  includes  the 
changed  module,  then  reboot  using  the  new  boot  file. 

•  To  use  the  patched  module  in  future  system  boots,  use 
&ME  to  store  the  module  in  the  MODULES  directory  ttf 
four  system  disk.  You  can  then  use  0S9GEN  to  create  a 
new  system  disk  using  the  patched  module.  If  you  are 
using  the  patched  module  to  replace  another  module, 
rename  the  original  module  and  then  give  the  patched 
module  the  original  name. 

•  If  you  patch  a  module  that  is  loaded  during  the  system 
boot,  you  can  use  COBBLER  to  make  a  new  system  boot 
that  uses  the  patched  module. 

Examples: 

The  following  example  shows  the  commands,  the  screen  prompts, 
and  the  entries  yaa  make  to  patch  the  standard  40-column  term 
window  descriptor  to  be  an  80-column  screen  rather  than  the 
standard  40-column  screen: 

0S9:build   termpateh  I  ENTER  | 

?    I    term  |  ENTER  | 

?  c   002c  28  50  I  ENTER  I 

?  c  0030  01  02 

?  V  I  ENTER  I 

?  I  ENTER  I 

□  S9:   modpatch   termpateh  |  ENTER  | 
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To  change  the  size,  columns,  and  colors  of  Device  Window  Wl, 
create  the  following  procedure  file  and  name  it  W180: 

I  wl 

c  0030  01  02 
c  002q  lb  50 
c  002d  Ob  18 

If  the  Wl  module  is  not  already  in  memory,  load  it  from  the 
MODULES  directory  of  your  system  disk.  Then,  before  initializ- 
ing Wl,  run  MODPATCH: 

modpatch  w1 80  fENTERl 

Istefej  Wlialize  Wl: 

shell    i  =  /w1  &  I  ENTER  | 

Press  1  CLEAR  I  to  display  the  new  window  with  80  columns,  24 
lines,  and  a  white  background. 
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MONTYPE 


Syntax:     moHtype  ffpe 

Function:  Sets  your  system  for  the  type  of  monitor  you  are 
using 

Parameters: 

Parameters: 

type  A  single  letter  indicating  the  monitor  type: 

c    for  composite  monitors  or  color  televisions 
r    for  RGB  monitors 

m  for  monochrome  monitors  or  black  and 
white  televisions 

Notes: 

•  Different  types  of  color  monitors  display  oiloFS  differently. 
Fbr  the  best  results,  set  your  system  to  the  type  of  monitor 
you  are  using. 

•  If  you  are  using  a  monochrome  monitor  or  black  and  white 
television,  you  can  obtain  a  sharper  image  by  setting  your 
monitor  type  to  monochrome. 

•  Include  the  MONTYPE  command  in  your  system's  Startup 
file  to  automatically  boot  in  the  proper  monitor  mode. 

•  If  you  do  not  use  MONTYPE,  the  system  de&ults  to  c  (eran- 
posite  monitor). 

Example: 

To  set  your  system  for  an  RGB  monitor,  type: 

montype   r  |  ENTER  | 
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To  add  a  MONTYPE  comowai,  to  existing  Startup  file,  first 
use  BUILD  to  create  the  new  ccanmand.  For  example: 

build   temp  |  ENTER  | 
mo n  type  r  |  ENTER  | 
I  ENTER  I 

Next,  append  the  file  to  Startup.  Type: 

merge  startup  temp  >  startup  .  new  pENTER  I 
Delete  tlie  tmsp  file: 

del   temp  |  ENTER  | 

To  enable  the  system  to  use  Startup.new  when  bootii^,  rename 
the  original  Startup  file: 

rename  Startup  Startup. old 

Then  rename  Startup.new: 

rename  Startup.new  Startup 
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OS9GEN 


Syntax:     os9gen  devname  [opts] 

Function:  Creates  and  links  the  required  OS9Boot  file  to  a 
diskette  making  it  a  bootable  diskette. 


Parameters: 

devname  The  disk  drive  containing  the  diskette  to 

receive  the  new  boot  file. 

opts  One  or  more  of  the  following  options. 

Options: 

-S  Causes  0S9GEN  to  use  only  one  drive  to  gen- 

erate the  hoot  file.  In  a  sfegte-dtive  operation, 
0S9GEN  reads  the  modules  fi-om  the  source 
diskette  and  asks  you  to  exchange  diskettes 
and  press  [T)  as  it  reads  and  ec^ies  the 
modules. 

#/i[K]  reserves  n  kilobytes  of  memory  for  use  by  the 

0S9GEN  command.  By  setting  aside  as  much 
memory  as  possible,  you  can  increase  the 
speed  of  0S9GEN  and,  on  single-drive  sys- 
tems, reduce  the  number  of  dUi^tte  swaps.  If 
you  type  K  after  #n,  the  memory  specified  by 
n  is  in  kilobytes  (1024  bytes),  otha:^se  n  is 
in  256-byte  pages. 

Notes: 

•  OS9BQot  filef  can  only  exist  on  contiguous  sectors.  Thra®- 
fore,  use  G®#(Si3N  only  with  newly  formatted  diataetfei.  If 
OS9Boot  is  fragmented,  the  system  ■Warns  you  not  to  use 
the  diskette  to  bootstrap  OS-9. 
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•  0S9GEN  creates  a  working  file  called  Teampboot  on  the 
device  specified  by  devname.  Next,  it  reads  filenames  (path- 
lists)  either  from  the  keyboard  (the  standard  input  path)  or 
redirected  from  a  file.  If  you  enter  names  manually, 
0S9GEN  does  not  display  a  prompt.  Type  each  filfflMtaMB 
and  press  |  ENTER  |.  After  typing  the  last  filename  and  |«piil5* 
ing  I  ENTER  I,  press  |  enter  |  again,  or  press  |  ctrl  |1  break  |  to  ccaft- 
plete  the  list. 

0S9GEN  opens  each  file  and  copies  it  to  Tempboot.  The 
process  repeats  until  it  reaches  a  blank  line  or  an  end-of- 
file  marker.  All  of  the  modules  listed  in  Chapter  5  are  not 
required  in  a  boot  file.  These  modules  must  be  included  in 
a  boot  File: 

OS9p2,  Init,  lOMan,  RBF,  SCF,  CC3I0,  VDGInt  (or 
Grflnt),  CC3Disk,  DO,  TERM,  Clock,  CC3G0. 

•  You  must  have  RENAME  in  the  current  execution  directory 
or  in  rtmmcf  &r  OSdGEN  to  wcwk  p^^]^. 


•  With  all  input  files  copied  to  Ifempboot,  0S9GEN  deletes 

the  OS9Boot  file,  if  it  exists.  It  renames  Tempboot  as 
OS9Boot,  and  writes  the  file's  starting  address  and  size  in 
the  diskette's  Identification  Sector  (LSN  0)  for  use  by  the 
OS-9  bootstrap  firmware.  OS-9  writes  its  kernel  on  diskette 
Tradk  S4.  If  tli^re  is  not  room  tbe  teael,  an  enror  mes- 
mppears,  and  the  operation  terminates. 

•  If  you  have  only  one  drive,  you  can  generate  a  new  boot  file 
more  easily  using  the  CONFIG  utility.  CONFIG  is 
designed  to  make  custom  system  diskettes  using  either  sin- 
gle- or  multiple-drives. 

Examples: 

•  The  following  commands  manually  install  a  boot  file  on 
device  /Dl  that  is  an  exact  copy  ^  the  OS9Boot  file  on 
device  /DO.  The  first  command  line  runs  0S9GEN,  the  seei- 
ond  enters  the  mama  of  the  file  to  iztitall,  &e  tMtd 
enters  an  eid-of-file  marker. 


osSgen    /dl  |  ENTER  | 


/d0/os9boot  I  enter  | 
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•  The  following  commands  let  you  manually  install  a  boot  file 
on  device  /Dl  that  is  a  copy  of  the  OS9Boot  file  on  device 
/DO  and  the  modules  stored  in  the  files  /DO/Tape. driver  and 
/D2/Video.driver.  Line  1  executes  0S9GEN.  Line  2  enters 
the  main  boot  filename.  Lines  3  and  4  enter  the  names  of 
the  two  additional  files,  and  Line  5  enters  an  end-of-file 
marker. 

os9gen   /dl  |  ENTER  | 
/d0/o59boot  I  ENTER  | 
/d0/tape. driver  |  ENTER  | 
/d2/video.  driver  |  ENTER  | 
rEfRTII  BREAK  I 

•  The  following  commands  generate  a  new  boot  file  on  Drive 
/Dl  that  includes  all  the  old  boot  file  modules.  Line  1  uses 
BUILD  to  create  a  file  called  Bootlist.  The  next  three  lines 
enter  the  names  of  the  three  files  into  Bootlist.  Line  5  ter- 
minates BUILD,  and  Line  6  runs  0S9GEN  with  input 
redirected  from  the  new  Bootlist  file. 

build   /d0/bootli5t  |  ENTER  | 
?   /d0/o59boot  I  ENTER  | 
t  /dl/i-ape.  driver  |  ENTER  | 
?  /d0/video. driver  1  ENTER  I 

?  I  ENTER  I 

os9gen  /d1</d0/boot  1  ist  | ENTER  | 

•  To  install  a  custom  boot  file  on  a  single-drive  system,  build 
a  Bootlist  to  drive  the  0S9GEN  program.  You  need  a  direc- 
tory that  contains  the  required  file  managers,  device  driv- 
ers, descriptors,  and  other  files  for  the  boot  file.  For 
example,  to  make  a  new  boot  file  containing  only  the 
/TERM,  /DO,  /Dl,  and  fP  devices,  first  build  a  Bootlist  such 
as: 
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build   /d0/boot  1  i  st  [enter] 

?  terni_vdq  ■  dt  |  ENTE"r1 

?  p  .  dd  I  ENTER  | 

?  d0_355  .dd  I  ENTER  | 

?  dT_355  .dd  I  ENTER  I 

?  059p2  I  ENTER  | 

?  Init  I  ENTER  I 

?  IQMan  |  ENTER  | 

?  RBF .  mn  |  ENTER  | 

?  CC3Disk  .  dr  |  ENTER  | 

?  SCF  .  mn  |  ENTER  | 

?  CC3ID.dr  I  ENTER  | 

?  vdgilit.lo  I  ENTER  | 

?  printer  .  dr  |  ENTER  | 

?  clock  .Sghz  lENTERl 

?  cc3go  I  ENTER  1 

Then  use  0S9GEN  to  create  the  new  boot  file  on  a  separate 
diskette  by  typing: 

osSgen    /d0    -5   #25K    </d0/bootll5t  |  ENTER  | 

This  command  causes  0S9GEN  to  use  only  one  drive,  25K 
of  buffer  space,  and  the  filenames  previously  stored  in  the 
Bootlist  file. 

%u  can  expand  this  basic  bootlist  file  to  include  other  stan- 
dard OS-9  modules  such  as  window  device  descriptors,  other 
disk  drivers,  descriptors,  and  terminal  or  modem 

descriptors. 

All  of  the  standard  bootlist  modules  are  contained  in  the 
MODULES  directory  on  the  BASIC09/CONFIG  didsette. 
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PROCS 


^mtax:    procs  [e] 

Function:  Displays  a  list  of  the  processes  running  on  the  sys- 
tem. PROCS  automatically  adjusts  its  ouipit  for  32-or  80- 
colunm  displays. 

Options: 

e  Causes  PROCS  to  display  the  processes  of  all 

users. 

Notes: 

•  Nonnally  PROCS  lists  only  processes  having  the  user's  ID. 
TbB  list  is  a  snapshot  taken  at  the  instant  PROCS  exe- 
cutes. Processes  switch  states  rapfMJy,  uKially  many  times 

per  second. 

•  PROCS  shows  the  user  and  process  ID  numbers,  priority, 
state  (process  status),  memory  size  (in  256  byte  pages),  pri- 
mary program  modute,  axd  standard  input  path. 

•  FROCS  adjusts  its  output  for  80  or  32  columns. 
Examples: 

•  Because  PROCS  automatically  adjusts  for  either  32-  or  80- 
column  displays,  the  following  command  can  produce  either 
format: 

proGS  e  I  ENTER  I 
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Ibllowing  TM  a  possible  32-coluixm  display  of  FROCS: 


Id  PId 

User# 

Pty 

Age  Sta 

Sigl 

Mem 

St  Pt  r 

Pr  imary 

a 

1 

0 

12@ 

128  $80 

i 

I7&i2 

Shell 

3 

@ 

0 

128 

128  $80 

a 

1  B 

$74B2 

Bas  i  c  09 

4 

2 

0 

128 

128  $80 

9 

S 

*0EF3 

5 

0 

0 

128 

128  $80 

0 

3 

$GFB2 

Shell 

6 

0 

0 

1  28 

123  $80 

0 

3 

$e8E2 

Shell 

Following  is  a  possible  80-column  display  of  PROCS: 

User  Heiii  Stack 

Id  PId  Number  Pty  ftge  Sts  Slgnl  Slz  Ptr    Primary  Module 

2  1       e  128  128  $8(      B      3  $78B2  Shell 

3  6       B  128  1  28  $8B      8     16  $7482  BasiM 

4  5       8  128  128  m      i      3  $72E2  Shell 

5  1       I  128  129  $81      i      3  $6FB2  Shell 

6  8       8  128  129  $82      I      3  $68E2  Shell 

7  4       8  128  128  $88      8      6  $85F3  Procs 
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PWD 
PXD 


Syntax:  pwd 
pxd 

Function:  PWD  shows  the  path  from  the  ROOT  directory  to 
the  current  data  dii&^lmy,  PXD  shows  the  path  from  the 
ROOT  directory  to  the  currmt  execution  directory. 

Notes: 

•  OS-9  keeps  a  current  data  directory  and  current  execution 
directory  for  each  proee^.  Use  PWD  and  PXD  to  ^tmr 
where  your  current  data  and  execution  directories  are 
located  on  the  disk  or  disks  you  are  using. 

Examples: 

•  Tim  Mkm^3stg  mmix^  nsm  a  Ml  pathlist.  CHD  changes 
the  curretst  fiita  directory  to  the  MANUMiS  directory. 

chd  /d1  /steve/tesctf  i  leia/maBttalS  |  ENTER  I 

To  displ^  the  full  path  to  the  data  directory,  type: 

pwd  jgNTEB] 

The  sa:e@Ei  d^i^ys  ^e  data  directory  path: 

/D1 /STEVE/TEXTFILES/MANUALS 

•  The  following  commands  cause  the  current  data  directory 
to  move  up  one  level  in  the  directory  hierarchy  and  then 
display  the  data  directoiy. 

chd    .  .  I  ENTER  | 
pwd  I  ENTER  I 

/D1/STEVE/TEXTFILES 


6-82 


System  Command  Descriptions  I  6 


•  The  following  commands  change  the  current  data  directory 
to  the  parent  directory  and  then  display  the  current  data 
directory. 

chd    .  .  I  ENTER  | 
pwd  I  ENTER  I 

/D1 /STEVE 

•  The  following  command  displays  the  extrrent  execution 

directory,  CMDS. 

pxd  I  ENTER  I 
/D0/CMDS 
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RENAME 

^^tax:    rename  patMist  ttlmmae 

Function:  Gives  the  specified  file  or  directory  a  new  name. 

Parameters: 

pathlist  The  current  name  of  the  file  or  directory. 

filename  The  new  name. 

Notes: 

•  Ibu  must  ham        ^gemdmim  M  ike  file. 
Examples: 

•  Tb  change  a  file's  name  from  Blue  to  Purple,  %pe: 

rename  blue  purple  I  ENTER  I 

•  Tq  rename  a  file  in  the  USEB9  directory  of  Drive  /D3,  type: 

rename  /d3/user9/teat  temp  |  ENTERI 

•  In  the  following  example,  DIR  displays  the  names  of  the 
files  in  the  current  data  directory,  RENAME  clmnges  the 
filmame  Animals  to  Mammals.  Another  DIR  command 
shows  ^lat  RENAME  has  performed  properly. 

dir  I  ENTER  I 

The  screen  displays: 

Directory  of    .  16:22:53 
my f  ile  animals 

rename  animals  mammals  |  ENTER  | 
dir  I  ENTER  I 
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The  srarem  now  shows; 

Directory  of  .  16:23:22 
myfile  mammals 
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SETIME 


Syntax:     setime  [yy/mm/dd  lili;jnijm[:ss]] 

Function:  Sets  the  system  date  and  time,  and  activates  the 
real  time  clock. 


Parameters: 

yy 

mm 

dd 

hh 

mm 

ss 


The  year  in  a  tvro-digit  format  (86  for  1986). 

The  month  in  a  one  or  two-digit  format  (01  or 
1  for  January,  12  for  Decembw), 

The  day  of  the  month  in  a  one-  or  two-digit 
format,  such  as  21. 

The  hoar  in  a  mB-  or  two-digit,  24-hour  for- 
mat (15  for  3  p.m.). 

Minutes  in  a  one-  or  two-digit  format,  such  as 

03,  5,  or  55. 

Seconds  in  a  one-  or  two-digit  format,  such  as 

04,  5,  or  25. 


Options: 

Specifying  seconds  in  the  new  time  entry  is  optional. 
Motes: 


•  Yaa  can  include  the  date  and  time  parameters.  If  you  do 
not,  SETIME  asks  you  for  them. 

•  Numbers  are  one-  or  two-  decimal  digits  using  the  space, 
cobn,  semicolon,  or  slash  as  delimiters. 

•  The  CC3go  module  starts  the  dock  on  system  startup,  so 
multitasking  is  possible  without  use  of  the  SETIME  utility. 
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•  If  you  do  not  set  the  date  and  time  when  booting  OS-9,  the 
system  cannot  accurately  update  the  "Last  modified"  date 
and  time  for  files. 

Examples: 

•  To  set  the  date  ajid  time  to  August  15,  1986,  3:45  p.m., 
type: 

setime  86, 08, 15, 15, 45  fENTER  | 

•  To  set  the  same  date  using  a  slightly  different  but  equally 
acceptable  format,  type: 

setime  86/08/15  15/45/08  [BITER J 
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Sjmtax:     setpr  procID  number 

Ftmctioii:  Changes  the  CPU  priority  of  a  process.  The  priority 
of  a  process  determines  the  CPU  time  allotted  to  it  under 
multi-tasking  conditions. 

Parameters: 

procID  The  number  of  the  process  for  which  you  want 

to  change  the  priority. 

number  The  new  priority  number. 

Notes: 

•  The  proceis  ptkitii^  number  is  a  deeteal  number  ha.  the 

range  1  (lowest  priority)  to  255.  If  you  need  information 
about  the  process  ID  number  and  current  priority,  use 
PROGS. 

•  Yaa  can  use  SETPR  only  on  processes  that  have  your  user 

number. 

•  SETPR  does  not  appear  in  the  CMDS  directory  because  it 
is  built  into  the  ^11. 

•  A  Super  User  (User  0)  can  set  any  process  piteities. 
Examples: 

•  To  set  or  change  the  priority  of  Process  8  to  250,  type: 

aetpr  8  250  [ENTER I 
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In  the  following  commands  PROCS  displays  process  ID 
numbers  and  other  information.  Then,  SETPR  sets  Process 
3  to  a  priority  of  255,  The  final  command  confirms  the 
change. 


pr  ocs  I  ENTER  1 

Ibllowing  is  a  sample  screen  display: 

User  Mem  Stack 

Id  PId  Number   Pty  Age  Sts  Signl  Siz  Ptr  Primary  Module 

2  1        8     128  128  m  B      3  $78E2  Shell 

3  S       B     128  128  m  0     16  $74B2  Ba5icB9 

4  2       B     128  128  m  i      S  «B5F3  Procs 

5  8       8    128  128  m  I     3  $6FB2  Shell 

6  t       i    128  1?9f8l  I  tlSflllhsU 


setpr  3  255  |  ENTER  | 
procs  I  ENTER  I 

User  Mem  StacV 

Id    PId  Number    Pty  Age  Sts  Signl  Siz    Ptr     Primary  Module 


f  1 

i    128  128  m 

1     3  $78B2  Shell 

3  « 

I    255  128  m 

1    16  »74B2  BasiceS 

4  5 

e    128  128  $88 

t      3  $72E2  Shell 

S  i 

a     128  129  $88 

B      3  $GFB2  Shell 

6  I 

I     128  129  m 

t      3  $68E2  Shell 

7  4 

I    128  128  $81 

I     6  $BSF3  Procs 
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SHELL 


Function:  The  shell  is  OS-9's  command  interpreter  program^.  It 
reads  data  from  its  standard  input  path,  processes  it  and 
sends  the  output  to  its  standard  output  path,  and  sends  error 
messages  (and  some  prompts)  via  the  standard  error  output. 
Any  or  all  of  these  paths  may  be  redirected.  It  interprets  the 
data  as  a  sequence  of  commands.  The  function  of  the  shell  is 
to  isitiate  and  control  execution  of  other  OS-9  programs. 

Parameters: 

arglist  The  commands,  parameters,  and  i^tiona  given 

SHELL  in  a  command  line. 

Notes: 

•  The  shell  reads  and  interprets  one  text  line  at  a  time  from 
the  standard  input  path  until  it  reaches  an  end-of-file 
marker.  At  that  time  it  terminates  itself 

•  When  another  program  calls  the  shell,  a  special  case  occurs 
in  which  the  shell  takes  the  argument  list  as  its  first  line 
of  input.  If  this  command  line  consists  of  built-in  com- 
mands only,  the  shell  reads  and  processes  more  lines.  Oth- 
erwise, control  returns  t©  the  calling  program  after  the 
sheU  pFQgesses  the  single  command  line. 

•  WisiR  ^(icftting  from  the  siiell,  you  do  not  need  to  specify 
fhiS  ^ELL  eomniand  to  execute  a  program,  a  cortmiand,  or 
a  built-in  shell  function.  Using  SHELL  before  a  command 
causes  the  existing  shell  to  fork  an  additional  shell,  which 
then  forks  the  s^pe^Q^  pweess,  such  as: 

shell  dire  |  ENTER  | 

Issuing  a  command  without  SHELL  6&U|tes  the  existing 
shell  to  fork  the  specified  process,  sudh  as: 

dir  e  |  ENTER  I 
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The  following  two  commands  also  have  identical  effects: 

shell  X  I  ENTER  | 
X  I  ENTER  I 

•  I!he  shdl  ccHmmand  separators  are: 

;  Sequential  execution  separator 

&        Concurrent  execution  separator 


I  ENTER  I  end-of-line  (sequentiial  ^cutte  sef  armtor) 
•  The  Shell  command  modifiers  are: 


»      Redirect  standard  error  output 

<>      Redirects  standard  input  and  standard  output 

<»    Redirects  standard  input  and  standard  error 
output 

»>    Redirects  standard  output  and  standard  error 

output 

<>>>  Redirects  standard  input,  standard  output  and 
standard  error  output 

#«      Set  the  process  memory  size  in  pages 

#«K    Set  the  program  memory  size  in  1  kilol^e  units. 

•  The  following  built-in  Shell  command  parameters  tell  OS-9 
to: 

chd  pathlist  Change  the  data  directctry 

kill  prodD  Send  the  termination  signal  to 


Pipeline  separator 


> 


< 


Redirect  standard  input 
Redirect  standard  output 


process 


setpr  procID 
number 


Change  the  specified  process 
priority 
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chx  pathlist  Change  the  execution  directory 

i-dmicename  Create  an  immortal  process 

w  '^B.it  for  any  process  to  die 

p  Turn  on  prompting 

-p  Turn  off  prompting 

t  Echo  input  Bnes  to  standard  output 

-t  Not  echo  input  lines 

-X  Not  terminate  on  an  errcr 

X  Iteninate  on  errcn: 

*  Not  process  the  following  text 

•  See  Chapter  8  fear  more  information  on  the  operation  ctf  the 
shell. 
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TMODE 


Syntax:    tmode  [patbaum]  [paramlis^  [...] 

Function:  Displays  or  changes  the  initiahzation  parameters  of 
the  terminal.  TMODE  automatically  adjusts  its  output  for  32- 
or  80-column  displays. 

Common  uses  include  changing  baud  rates  and  control  key 
di^nitions. 


Parameters: 

pathnum         One  of  the  standard  path  numbers: 


.0  =  standard  input  path 

.1  =  standard  output  path 

.2  =  standsird  error  output  path 


paramlist 


One  of  the  Mlowing  options. 


Options: 


upc 


Displays  uppercase  characters  only.  Lowercase 
characters  automatically  convert  to  uppercase. 


•upc 


Displays  both  upper-  and  lowercase  characters. 


bsb 


Causes  a  backspace  to  erase  characters.  Back- 
space clraracters  ei^  as  a  b£u^ipt(^i|>sce> 
backspace  sequence.  This  setting  is  the  system 

default. 


-bsb 


Causes  backspace  not  to  erase.  Only  a  single 
backspace  echoes. 


bsl 


Enables  backspace  over  a  line.  Deletes  lines  by 
sending  backspace-space-backspace  sequences 
to  erase  a  line  (for  "ddeo  terminals).  This  set- 
ting is  the  system  default. 
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-bsl  Disables  backspace  over  a  line.  To  delete  a  line, 

TMODE  pints  a  new  line  sequence  (for  hard- 
copy terminals). 

echo  Input  characters  echo  on  the  tOTminal.  This 

setting  is  the  system  default. 

-echo  Turns  off  the  echo  default. 

If  Turns  on  the  auto  line  feed  function.  Line 

feeds  automatically  echo  to  the  terminal  on 
input  and  output  carriage  returns.  The  auto 
line  MeS.  setting  is  the  system  defeiult. 

-If  Txmm  ^  ite  mio  Im@  Hed  d^olt. 

n!oll  =ra  Sets  the  null  ccnint— the  ntmiher  of  null  ($00) 

characters  transmitted  after  carriage  returns 
for  the  return  delay.  The  value  n  is  in  decimal. 
The  default  is  0. 

pause  Turns  on  the  screen  pause.  This  setting  sus- 

pends output  when  the  screen  fills.  See  the 
pag  parameter  for  a  definition  of  screen  size. 
Resume  output  by  pressing  the  space  bar.  This 

setting  is  the  system  default. 

-pause  Turns  off  the  screen  pause  mode. 

pag  =  n  Sets  the  length  of  the  video  display  page  to  n 

(decimal)  lines.  This  setting  affects  the  pause 
mode. 

bsp=A  Sets  the  backspace  character  for  input.  The 

value  h  is  in  hexadecimal.  The  de&ult  is  08. 

iiA=k  Sets  the  delete  line  character  itr  in|mt.  The 

value  h  is  in  hexadecimal,  The  default  is  18. 

ear=fe  Sets  the  end-of-record  (carriage  return)  char- 

acter for  input.  This  setting  requires  a  value 
in  hexadecimal.  The  default  is  OD. 

eo£=h  Sets  the  end-of-file  character  for  input.  The 

value  A  is  in  hexadecimal.  The  default  is  IB. 
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reprint = A       Sets  the  reprint  line  charade.  Hie  value  h  is 

in  hexadecimal. 

dwp  =  h  Sets  the  character  to  duplicate  the  last  input 

line.  The  value  h  is  in  hexadecimal.  The 
default  is  01. 

psc=h  Sets  the  pause  character.  The  value  of  the 

character  is  in  hexadecinial.  The  default  is  17. 

abort =^        Sets  the  teiminate  dharaicter  CnonnaQsr  (XM- 
TROL  C).  The  value  of  the  character  is  in 

hexadecimal. 

quit  =  /i  Sets  the  quit  character  (normally  CONTROL 

E).  The  value  of  the  character  is  in 

hexadecimal. 

hse  =  h  Sets  the  backspace  character  for  output.  The 

value  ^  is  in  h^caieciinal.  The  d^ault  is  08. 

bdl=A  Sets  the  bell  (alert)  character  fer  output.  The 

value  h  is  in  hexadecimal.  The  default  is  07. 

type=^  For  external  devices,  use  type  for  ACTA  (asyn- 

chronous communications  interface  adapter) 
initialization  values  (hexadecimal).  The 
default  is  00.  Bits  6-7  set  either  MARK, 
SPACE,  or  no  parity  on  all  devices.  Codes  for 
these  are: 

000  =  no  parity 

101  =  MARK  parity  transmitted,  no 
checking 

111  =  SPACE  parity  transmitted,  no 
checking 

Oil  =  even  parity  (available  only  with 
the  external  ACIA  pak  and  Mod- 
pak  devices) 

001  =  odd  parity  (available  only  with 

the  external  ACIA  pak  and  Mod- 
pak  devices) 
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Bit  4  selects  auto-answer  modem  support  fea- 
tures, 

1  =  m 

0  =  off 

See  "Technical  Information  for  the  RS232 
Port"  in  Chapter  5  for  more  information. 

For  TERM-VDG,  the  type  byte  has  a  different 

use: 

Bit  0  specifies  a  machine  with  true  low- 
ercase capability.  Set  Bit  0  to  tarn  on. 
true  lowercase. 

Ibr  TERM- WIN,  use  a  value  of  80  to  specify  a 
window  device. 

xon=^  Sets  the  character  to  be  used  as  a  signal  for 

resuming  transmission  of  data  after  an  xoff 
signal  is  received.  Default  is  0  (not  active). 

xoff=^  Sets  the  character  to  be  used  for  stopping  data 

li'attsmission.  Default  is  0  (not  active). 

baud!=A  Sets  the  battdfate,  word  length,  and  stop  bits 

for  a  software-controllable  interface.  The  codes 
for  the  baud  rate  are: 

0  =  110    3  =  1200    6=  9600 

1  =  300    4  =  2400    7  =  19200  (ACIAPAK  only) 

2  =  600    5  =  4800    7  =  32000  (SIO  only) 

Bits  0-3  determine  the  baud  rate. 
Btl  4  is  rgrefvSd  for  future  use. 
Bits  5-6  determine  the  word  length: 

00  =  8  bits 

01  =  7  bits 

Bit  7  determines  the  number  of  stop  bits: 

0  =  1  stop  bit 

1  =  2  stop  bits 

See  "Technical  Information  for  the  RS232 
Port"  in  Chapter  5  for  further  information. 
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Notes: 

•  You  can  specify  any  number  of  parameters  from  the  options 
list,  separating  them  by  spaces  or  commas.  If  you  don't 
specify  parameters,  TMODE  displays  the  current  values  of 
the  available  options. 

•  You  can  use  a  period  and  a  number  to  specify  the  pathnum- 
ber  on  which  to  read  or  set  options.  If  you  don't  specify  a 
path,  TMODE  affects  the  standard  input  path. 

•  TMODE  works  only  if  a  path  to  tiie  file/device  is  open.  Use 
XMODE  to  alter  device  descriptors  and  set  device  initial 

operating  parameters. 

•  TMODE  can  also  alter  the  baud  rate,  word  length,  stop 
bits,  and  parity  for  devices  already  initialized, 

•  If  you  use  TMODE  in  a  procedure  file,  you  must  specify  one 
of  the  standard  output  paths  (.1  or  .2).  This  procedvue  is 
necessary,  heeause  the  command  redirects  the  SHELL'S 
standard  input  path  to  come  from  a  disk  file.  (You  can  use 
TMODE  only  on  SCFMAN-type  devices.)  For  example,  to 
set  lines  per  page  for  standard  output,  use  this  line: 

TMODE  .1   pag  =  24  [mm] 

Examples: 

•  The  following  command  line  sets  the  terminal  to  display 
upper-  and  lowercase,  sets  the  null  count  to  4,  and  turns  on 
the  screen  pause  function. 

tmode  -upc  If  nul  l  =  4  pause  |  ENTER  | 

•  The  next  command  sets  the  screen  page  length  (number  of 
lines)  to  24,  turns  on  the  screen  pause  function  and  the 
backspace-over-line  function,  and  sets  the  backspace  charac- 
ter value  to  8  and  turns  off  the  echo  de&ult. 

tmode  pag=24  pause  bsl  -echo  bsp  =  8  (JNTER] 
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TUNEPORT 

Syntax:     tuneport  [device]  [-s  =  value] 

Functioii:  Lets  you  test  and  set  delay  loop  values  for  the  cur- 
rent baud  rate  and  select  the  best  value  for  your  printer  or 
terminal. 


Parameters: 

device 

value 


The  device  you  want  to  test,  either  your 

printer  (/p)  or  terminal  (/tl). 

A  new  delay  loop  value. 


Options: 

-s  =  Sets  a  new  d^s^  toc$  vakie. 

Examples: 


•  The  foUowiiig  cominand  provides  a  test  operation  for  your 
printer. 

tuneport    /p  |  ENTER  | 

After  a  short  delay,  TUNEPORT  displays  the  current  baud 
rate  and  smSis  data  to  tlas  printer  to  see  if  it  is  working 
properly.  The  program  then  displays  tite  current  delay  value 
and  asks  for  a  new  value.  Enter  a  decimal  delay  value  and 
press  I  ENTER  |.  Again,  TUNEPORT  sends  data  to  the  printer 
as  a  test.  Continue  this  process  until  you  find  the  best 
value.  When  ym  am  satimed,  iWlEB  i  tost^id  of  @Ete- 
ing  a  value  at  the  prompt.  A  closing  message  (Usplays  your 
new  value. 

Use  the  same  process  to  set  a  new  delay  loop  value  for  the 
/Tl  terminal. 
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•  The  following  command  line  sets  the  dele^  li>^  value  for 
your  printer  to  255. 

tuneport  /p  -5  =  255  |  ENTER  | 

Use  such  a  command  on  future  system  boots  to  set  the  opti- 
mum delay  value  determined  with  the  TUNEPORT  test 
function.  Then,  using  0S9GEN  or  COBBLER,  generate  a 
new  boot  file  for  your  system  diskette.  You  can  also  use  the 
-s  option  with  TUNEPORT  in  your  system  Startup  file  to 
set  the  value. 
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UNLINK 


%itte^l    mMnh  modname  l...} 

FuneMomt:  Tdls  OS-9  that  the  n£iined  memory  module(s)  is  no 

P^ameters: 

modname        One  or  more  modules  you  \vant  to  unlink. 

Options: 

In  one  command  line,  you  can  specify  as  many  modules  as  you 
want  to  unlink. 

Notes: 

•  Whether  OS-9  destroys  the  modules  and  reassigns  their 

memory  depends  on  whether  the  module  is  in  use  by  other 
processes.  Each  process  using  a  module  increases  its  link- 
count  by  one.  Each  UNLINK  you  issue  decreases  its  link- 
count  by  1.  When  the  link-covmt  reaches  0,  OS-9  deallo- 
cates the  module. 

•  ^u  shotdd  unliiik  modules  whenever  possible  to  make  most 

efficient  use  of  available  memory  resources.  Modules  you 
have  loaded  and  linked  might  need  to  be  unlinked  twice  to 
remove  them  from  mjemcnry. 
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•  Warning:  Never  attempt  to  unlink  a  module  you  didn't  load 
or  link,  and  never  unlink  a  module  that  is  in  use  by  pro- 
grams (displaj^  by  the  PROCS  conunand). 

Examples: 

•  To  unlink  three  modules  named  Pgml,  Pgm5,  and  Pgm99, 
type: 

unlink   pgml    pgm5  pqm99  |  ENTER  | 

•  In  the  foUowiiig  command  sequence,  MOIR  first  displays 
the  modules  in  memory.  T!hs  next  command  unlinks  the 

edit  module.  The  output  of  the  final  command  (MDIR) 
shows  that  UNLINK  is  successful — Edit  no  longer  appears 
on  the  list. 

mdir  |  ENTER! 

A  possible  screen  display  is: 


Modu 1 e 

Directory  at 

20:01  :08 

Soot 

QS9p1 

QS9p2 

Init 

RBF 

CCSBlsk 

m 

D1 

DD 

SCF 

CC3I0 

VDGInt 

Orfint 

TERM 

U1 

M2 

M3 

U4 

US 

m 

W7 

ACIAPAK 

T2 

PRINTER 

p 

PipeMas 

Piper 

Pipe 

Clock 

CC3Go 

CC3ffli5k 

H0 

Shell 

Copy 

Date 

DEIniz 

Del 

Dir 

Display 

Echo 

Iniz 

Link 

List 

Load 

MDir 

Metge 

Wffee 

Proes 

Setiine 

Tmode 

Unlink 

Ba5ic09 

©rfDi'v 

Edit 

unlink  edit  |  ENTER  | 
mdir  I  ENTER  I 
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The  new  screen  display  is: 

Module  Directory  at  00:03:15 


REL 

Boot 

0S9pt 

aS9p2 

Init 

IQMan 

RBf 

CC3Disl( 

D0 

D1 

DD 

SCF 

CCSID 

VDGInt 

Grf Int 

TERM 

N 

W1 

W2 

N3 

U4 

1*15 

m 

W7 

ACIAPAK 

T2 

PRINTER 

p 

PipeMan 

Piper 

Pipe 

Clock 

CCSGo 

CC3HDi5k 

H0 

Shell 

Copy 

Date 

Delniz 

Del 

Dir 

Display 

Echo 

Inlz 

Link 

List 

Load 

MDir 

Merge 

Wf  ree 

Procs 

Rename 

Setime 

Tmode 

Unlink 

BaslciS 

GrfDrv 
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WCREATE 


Syntax:     wcreate  /wpatb  [s  =  type]  xpos  ypos  xsize 
ysize  foregrovmd  background  [border] 

Function:  Initializes  and  creates  a  window. 


Parameters: 


Iwpath  The  window  device  name  of  the  window  you 

are  creating  (W,  Wl,  W2,  W3,  and  so  on). 

xpos  The  X  co-ordinate  (in  decimal)  for  the  starting 

position  of  the  upper  left  comer  of  the  screen. 

ypos  The  y  co-ordinate  (in  decimal)  for  the  starting 

position  of  the  upper  left  corner  of  the  screen. 

xsize  The  horizontal  size  of  the  screen  in  columns;  1 

to  80  (in  decimal)  for  screen  types  2,  5,  and  7, 
and  1  to  40  (decimal)  for  screen  types  1,  6, 
and  8. 

ysize  The  vertical  size  of  the  screen  in  lines,  in  the 

range  1  to  24  (in  decimal). 

foreground       The  window  foreground  color. 

bmkgrottftd     The  window  background  color. 

border  An  optional  window  bordra*  color.  The  dAult 

is  black. 

Optbns: 

-a- type  The  screen  type,  chosen  from  the  foUowihg 


list: 

Type  Description  

1  =  40-column  hardware  text  screai 

2  =  80-column  hardware  text  scre^ 

5  =  640  X  192  two^^Ii9r  §i^©^ 

6  =  320  X  192  four-color  screen 
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7  =      640  X  192  four-color  scretJi 

8  =     320  X  192  sixte^-Golor  weami-- 

If  ym  use  tlie  -^=type  option,  you  mmt  spec- 
ify a  border  color  in  the  command  line.  The  -s 
option  is  only  used  to  create  a  window  on  a 
new  screen.  When  creating  additional  windows 
on  the  currently  displayed  screen,  omit  the  -s 


Examples: 

•  To  create  a  full  screen,  80-column  text  window  on  /wl, 
type: 

weriiafeg  /w1  ".sfst  I  f  Wi       f  4  1  I  enter  | 

•  To  create  two  windows  (/w2  and  /w3)  on  a  840  x  192  graph- 
ics screen  in  which  /w2  is  the  upper  left  of  the  display  and 
/w3  is  the  right  half  of  the  display,  first  use  build  to  create 
an  input  file: 

build  wf  ile  |  ENTER  | 

?  /w2  -a  =  07  0  a  40  1  2  7  4  1  |  ENTER  | 
?   /w3  40  0  40  24  4  7  |  ENTER  | 
?  I  ENTER  I 

Then,  create  the  windows  using  Wfile  as  input: 

wcrea  te  -z  <  wf  i  le  [INTER  | 


-Z 


Produces  a  help  message  for  the  command. 
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•  You  can  use  the  -z  option  to  create  windows  in  yovir  system 
startup  fflb.  Wmr  w^mphe,  &e  following  startup  file  sets  up 
several  windows,  along  with  the  usual  SETIME. 

•  lock   the  shell  in  memory  and  set  the  time 
link  shell 

setlme  <  /1 

»  create  the  new  Windows 

wc  r  ea  t  e   -  z 

•  set   up  an  80-column   full   window  for  /w1 
/w1    -s=2   0   0   80   24   7  4  1 

•  set  up  a  40  column  full  window  for  /w2 
/w2  -s-1    0  0  40  24  7  4  1 

•  set  up  /w3  and  /w4  as  halves  of  a 
*640  X   192  display 

/w3  -5=7   0   0   40   24  7  4  1 
/w4  40  0  40  24  4  7 

•  the  following  fcilank  line  terminates  input 

•  from  wcreate 


•  get  the  graphics  fonts  loaded 

merge   sys/stdfonts   >  /w1 

Now,  when  the  system  boots,  it  has  four  windows  defined, 
besides  TEEM.  As  shown,  you  can  use  an  asterisk  as  the 
first  character  on  a  line  in  order  to  albw  comments  in  the 
file. 
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XMODE 


%iitax:    xmode  devname  [parainlis^ 

Function:  Displays  or  changes  the  initialization  parameters  of 
any  SCF-type  device  such  as  the  video  display,  printer, 
RS-232  port,  and.  others.  XMODE  automatically  adjusts  its 
output  w  ti^  «  SCfc'^tain  displays. 

iSmicmm  xme»  telud^  changing  baud        ms&  em^t 
deSnitions. 


Parameters: 

pathnum 

paramlist 
Options: 
upc 

-upc 
bsb 

-bsb 
bsl 

-bsl 


The  device  nanie  to  change,  such  as  /term, 
/w7,  /t2,  and  m  on. 

One  of  the  Mlowing  options. 


Displays  uppercase  characters  only.  Lowercase 
characters  automatically  convert  to  uppercase. 

Displays  both  upper-  and  lowercase  characters. 

Causes  a  backspace  to  erase  characters.  Back- 
space cIiEEraefeiPS  edtio  as  a  bad^^mee-spaee- 
backspace  sequence.  This  setting  is  the  system 

default. 

Causes  backspace  not  to  erase.  Only  a  single 
backspace  echoes. 

Enables  backspace  over  a  line.  Deletes  lines  by 
isxiding  backspace-space-backspace  scqp^iees 
to  erase  a  line  @fo  vl^  tmn&aU^  ^EUs  set- 
ting is  the  syst^  de&ttlt. 

Disables  backspace  over  a  line.  To  delete  a  line, 
you  must  print  a  new  line  sequence  (for  hard- 
terminals). 
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echo  Input  characters  echo  on  the  terminal.  This 

setting  is  the  system  default. 

-echo  Twtm  off  the  echo  dAolt. 

If  Turns  on  the  auto  line  feed  ftinction.  Line 

feeds  automatically  echo  to  the  terminal  on 
input,  and  they  output  carriage  returns.  The 
auto  line  feed  setting  is  the  system  d^ult. 

-If  Turns  off  the  auto  line  feed  default. 

null  =  n  Sets  the  null  count — the  number  of  null  ($00) 

characters  transmitted  after  carriage  returns 
for  the  return  delay.  The  value  n.  is  in  decintaL 
The  default  is  0. 

pause  Turns  on  the  screen  pause.  This  setting  sus- 

pends output  when  the  screen  fills.  See  the 
pag  parameter  for  a  definition  of  screen  size. 
Resume  output  by  pressing  the  space  bar.  This 
setting  is  the  system  default. 

-pause  Turns  off  the  screen  pause  mode. 

pag  =  re  Sets  the  length  of  the  video  display  page  to  n 

(decimal)  lines.  This  setting  affects  the  pause 

mode. 

hsp  =  h  Sets  the  backspace  character  for  input.  The 

value  h  is  in  hexadecimal.  The  default  is  08. 

diA  =  h  Sets  the  delete  line  character  for  input.  The 

value  h  is  in  hexadecimal.  The  default  is  18. 

&or=h  Sets  the  end-of-record  (carriage  return)  char- 

acter for  input.  This  setting  requires  a  value 
in  hexadecimal.  The  default  is  OD. 

eo£=h  Sets  the  end-of-file  character  for  input.  The 

value  h  is  in  hexadecimal.  The  default  is  IB. 

reprint  =  A       Sets  the  reprint  line  character.  The  value  h  is 
in  hexadecimal. 

d\ip  =  h  Sets  the  character  to  duplicate  the  last  input 

line.  The  value  h  is  in  hexadecimal.  The 
de&ult  is  01. 
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p8c  =  h 
abort  =  /i 

qmt=/i 

bse  =  ^ 
bell  =  /^ 
%pe = h 


Sets  the  pause  character.  The  value  of  the 
character  is  in  hexadecimal.  The  default  is  17. 

Sets  the  terminate  character  (normally  CON- 
TROL C).  The  value  of  the  character  is  in 
hexadecimal. 

Sets  the  quit  character  (normally  CONTROL 
E).  The  value  of  the  character  is  in 
hexadecimal. 

Sets  the  backspace  character  for  output.  The 
value  h  is  in  hexadecimal.  The  default  is  08. 

Sets  the  bell  (alert)  character  for  output.  The 
value  A  is  in  hexadecimal.  The  de&ult  is  07. 

Bar  ^Eternal  devibes,  use  type  ftr  ACIA  (asyn- 
chronous communications  interface  adapter) 
initialization  values  (hexadecimal).  The 
default  is  00.  Bits  5-7  set  either  MARK, 
SPACE,  or  no  parity  on  all  devices.  Codes  for 

000      BO  parity 

101  =  MARK  parity  trattgiolttedl,  m 


111  =  SPACE  parity  transmitted,  no 

checking 

Oil  =  even  parity  (available  only  with 
the  external  ACIA  pak  and  Mod- 

pak  devices) 

001  =  odd  parity  (available  only  with 
&e  eeifiiCT^  ACIA  pak  and  Mod- 
pak  devices) 

Bit  4  selects  auto-answer  modan  support  fea- 
tures. 

1  =  on 

0  =  off 

See  "Technical  Information  for  the  RS232 
Port"  in  ChaptOT  5  for  more  information. 


System  Command  Descriptions  I  6 


For  TERM-VDG,  the  type  byte  has  a  different 
use: 

Bit  0  specifies  a  mo^ubie  with  true  low- 
ercase capability.  Set  Bit  0  to  turn  on 

true  lowercase. 

For  TERM-WIN,  use  a  value  of  80  to  specify  a 
window  device. 

baud  =  ^  Sets  the  baud  rate,  word  length,  and  stop  bits 
for  a  software-controllable  interface.  The  codes 
for  the  baud  rate  are: 

0  =  110    3  =  1200    6=  9600 

1  =  300   4  =  2400   7  =  19200  (ACIAPAK 

only) 

3  =  600    5  =  4800    7 =32000  (SIO  wly) 

Bits  0-8  determine  the  baud  rate 

Bit  4  is  reserved  for  future  use 
Bits  5-6  determine  the  word  length: 

00  =  8  bits 

01  =  7  bits 

Bit  7  detKiiiiMig  the  number  ci  stop  bits: 

0  =  1  stc|»  Mt 

1  =  2  stop  bits. 

See  "Technical  Information  for  the  RS232 
Pbrt"  in  Chapter  5  for  farther  information. 

7Bon=h  Sets  the  character  to  be  used  as  a  signal  for 

resuming  transmission  of  data  after  an  xoff 
signal  is  received.  De&ult  is  0  (not  active). 

xofF=  h  Sets  the  ^orad^  fo  be  used  for  stuping  data 

transmission.  De&ult  is  0  (not  active). 
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Notes: 

•  XMODE  is  similar  to  TMODE,  but  there  are  differences. 
TMODE  operates  only  on  open  paths,  so  its  effect  is  tempo- 
fmf  .  !XM0D1  tipdates  the  divlce  descrfptor.  Iti  ehaaige  per- 
sists as  long  as  the  computer  is  running,  even  if  you  or  the 
system  repeatedly  open  and  close  the  paths  to  the  device. 

•  If  you  use  XMODE  to  change  parameters  and  the  COB- 
BLER program  to  make  a  new  system  diskette  or  to  re- 
make the  boot  tracks  on  the  current  system  diskette,  the 
process  permanently  changes  the  pBWas&d^m  on  the 
system  diskette. 

•  XMODE  requires  that  you  specify  a  device  name.  If  you  do 
not  specify  parameters,  XMODE  displays  the  present  value 
for  each  parameter.  You  can  use  any  number  of  parametOTs, 
separating  them  with  spaces  or  conunas. 

Examples: 

•  The  following  command  sets  the  term  (video)  for  upper-  and 
lowercase,  the  null  count  to  4,  the  backspace  character 
value  to  IF  hexadecimal,  and  turns  on  the  screen  pause 
tection. 

xmode  /term  -upe  Bull*4  bse^lF  pause  |  ENTER  | 
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Overview 

The  OS-9  Macro  Text  Editor  is  a  powerful,  easy-to-learn  text- 
preparation  system.  Use  it  to  prepare  text  for  letters  and  docu- 
ments or  text  to  be  used  hy  other  OS-9  programs,  such  as  the 
assembler  and  high-level  languages.  The  text  editor  includes  the 
following  features: 

•  Compact  size 

•  Capability  of  having  multiple  read  and  write  files  open 
at  the  same  time 

•  All  OS-9  commands  usable  inside  the  text  editor 

•  Adjustable  workspace  size 

•  RepeataUe  command  sequences 

•  Edit  macros  (speeial  utility  functions) 

•  Multiple  test  buffers 

•  Powerful  commands 

The  Macro  Text  Editor  is  about  5  kilobjrtes  in  size  and  requires 
at  least  2K  bytes  of  free  RAM  to  run. 

Text  Buyers 

As  you  enter  text,  the  editor  places  it  in  a  temporary  storage 
area  called  a  text  buffer.  A  text  buffer  acts  as  a  scratch  pad  for 
saving  text  that  you  can  maripulftt©  with  various  edit  emn- 
mmis.  The  Macro  Text  Editor  can  use  multiple  text  buffers,  one 
at  a  time. 

A  buffer  in  use  is  called  the  edit  buffer.  Edit  also  has  another 
default  buffer  called  the  secondary  buffer.  As  well,  you  can  create 
additional  buffers  up  to  the  capacity  of  your  computer's  memory. 

The  Macro  Text  Editor  has  an  edit  pointer  that  identifies  your 
position  in  the  buffer,  in  a  manner  similar  to  holding  your  place 
in  a  book  with  your  finger. 
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The  poixilca:  is  invisible  to  you,  but  Edit  commands  can  reposi- 
tion it  and  displs^  the  to  which  it  paints.  Each  btifC^  has  its 
own  edit  pointer,  and  you  can  move  from  buffer  to  buffer  without 

losing  your  place  in  any  of  them. 

Entering  Commands 

The  Macro  Text  Editor  is  interactive.  This  means  you  and  the 
editor  carry  on  a  two-way  conversation.  You  issue  a  command, 
and  the  editor  carries  out  the  command  and  displays  the  result. 
When  you  are  through  making  changes,  you  can  save  your 
edited  file,  then  p®ss  [3]  I  enter  i  to  quit  e^tiiig. 

When  the  editor  dilplsry^  E :  on  the  sereen,  it  is  waiting  fer  you 

to  type  a  command.  Yo\x  type  a  line  that  includes  one  or  more 
commands,  then  press  I  enter  |.  Edit  carries  out  the  commands  and 
again  displays  E : . 

If  you  enter  more  than  one  command  on  a  line,  separate  the 
commands  with  a  space.  If,  however,  a  space  is  the  first  charac- 
ter on  a  line^  the  et^tof  mmsTtSjim  the  spaM  to  be  an  insert  com- 
mand and  not  a  separates'. 

Correct  a  typing  error  by  backspacing  over  it  or  by  deleting  the 
entire  line.  Note,  you  cannot  correct  a  line  after  pressing  I  enter  |. 

Control  K^s 

"%u  can  use  the  same  special  control  keys  with  Edit  that  you 
use  with  OS-9.  See  Appendix  D  for  a  complete  listing  of  these 
keys.  Following  is  a  list  of  some  of  the  control  keys  that  are  espe- 
cially useM  with  Edit: 


Control  Ei^(s) 

Function 

1  CTRL  1  [AJ 

Repeats  the  previous  input  line. 

1  CTRL  1  [£) 

Tterminates  the  editor  and  returns  to  com- 

mand entry  mode. 

(CTRL J,  [d] 

Displays  the  current  input  on  the  next  line. 

1  CTRL  1  d] 

Backspaces  and  erases  the  previous 

or  H 

character. 

Macro  Text  Editor  I  7 


iCtMxtrol  Key(s)  Function 


(T)  I  ENTER  I  Interrupts  the  editor  and  returns  to  com- 

mand entry  mode. 


I  GTRi  I  rWI  Temporarily  halts  the  data  output  to  your 

terminal  so  that  you  can  read  the  screen 
before  the  data  scrolls  off.  Output  resumes 
when  you  press  any  other  key. 

I  CTRL  I  (Y)  or  Deletes  the  line. 

rSHIFfl  B 

I  CTRL  1 1  BREAK  |  Terminates  the  editor,  and  returns  to  com- 

mand entry  mode. 

Command  Parameters 

Theare  are  two  types  of  edit  parameters,  "numeric"  and  "string." 

Nttmerie  Parameters.  Numeric  parameters  specify  aft  amount, 

such  as  the  number  of  times  to  repeat  a  command  or  the  number 
of  lines  affected  by  a  command.  If  you  do  not  specify  a  numeric 
parameter,  the  editor  uses  the  default  value  of  one.  Specify  all 
other  numeric  parameters  in  one  of  the  following  ways. 

•  Enter  a  positive  decimal  integer  in  the  range  0  to 
65,533.  Est  tsmm^: 

0 

10 

5250 

65532 
31 

•  Enti^  an  asterisk  (*)  as  a  shorthand  for  all  (all  the  way 
to  the  beginning,  all  the  way  to  the  eatid,  all  of  the  lines, 

and  so  on).  To  the  editor,  an  asterisk  means  infinity.  Use 
the  asterisk  to  specify  all  remaining  lines,  all  charac- 
ters, or  repeat  forever. 

•  Use  a  numeric  variable.  (See  "Parameter  Passing"  later 
in  this  chapter.) 
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String  Parameters.  String  parameters  specify  a  single  charac- 
ter, group  of  characters,  word,  or  phrase.  Specify  string  parame- 
ters in  either  o£  the  following  ways. 

•  Enclose  the  group  of  characters  with  delimiters  (two 
matching  characters).  You  can  use  any  characters,  but 
they  must  match.  If  one  string  immediately  follows 
another,  separate  the  two  with  a  single  delimiter  that 
matches  the  others.  For  example: 

"string  of  characters" 
/STRING/ 

;   my  name  is  Larry  : 

"first  strlng"seeond  string" 

/sir tng  1/  string  2/ 

•  Use  a  string  variable.  (See  "Using  Macros"  later  in  this 
chapter.) 

Syntax  Notation 

iSyiitax  desjcriptions  indicate  what  to  enter  and  the  order  in 
wiiich  to  do  it.  The  command  name  is  first;  type  it  exactly  as 
shown.  Follow  the  command  name  with  the  correct  parameters. 
Enter  each  as  it  is  described  in  the  section  on  parameters. 

The  syntax  descriptions  for  each  command  use  the  following 
notations: 

n  =  numeric  parameter 
str  -  string  parameter 

□  =  space  character.  When  you  see  D,  press  the  space  bar. 
text  =  one  or  more  characters  terminated  by  pressing 

I  ENTER  I 

Getting  Started 

From  the  OS-9  prompt,  start  Edit  by  typing: 

edit  I  ENTER  | 

Enter  a  command  when  the  screen  shows  E : . 

"55)u  can  quit  Edit  at  any  time  by  pressing  (T|  I  enter  |.  The  Q  com- 
mand terminates  the  editor  and  returns  you  to  the  OS-9  Shell, 
which  responds  with  the  0S9 :  prompt. 
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Following  is  a  list  trfways  you  can  start  the  editor,  including  the 
effect  of  each.  The  examples  call  a  file  that  already  exists  oldfile. 
The^  call  a  file  to  be  created  newfih. 

EDIT  OS-9  loads  the  editw  and  starts  it.  "rhe  eotn- 

mand  does  not  establish  an  initial  read  or 
write  files,  but  you  can  perform  text  file  opera- 
tions by  opening  files  after  the  editor  is 

started. 

EDIT  newGle     OS-9  loads  the  editor  and  starts  it,  creating 
the  file  called  mwftte.  Mmfik  is  ihs  initial 

write  file.  There  is  no  initial  read  file.  How- 
ever, you  can  open  files  to  read  later. 

OS-9  loads  the  editor  and  starts  it.  The  initial 
read  file  is  oldfile.  The  editor  creates  a  file 
called  SCRATCH  as  the  initial  write  file. 
When  ymi  end  the  edft  session,  OS-9  deletes 
oldfik  and  renames  SCRATCH  to  oldfile.  This 
gives  the  appearance  of  oldfile  being  updated. 

Note:  The  two  OS-9  utilities  DEL  and 
RENAME  must  be  present  on  your  sy8t«i  if 
you  wish  to  start  the  editor  in  this  manner. 

OS-9  loads  ibs  editor  and  starts  it.  The  initial 
read  file  is  oldfile.  The  editor  creates  newfile — 
the  initial  write  file.  The  terms  oldfile  and 
newfile  refer  to  any  properly  constructed  OS-9 
pathlist. 


EDIT  oldGle 


EDIT  oldGle 
MnewSle 
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Edit  Commands 


Displaying  Text 

Lji  Lists  (displays)  the  next  n  lines,  starting  at 

the  current  position  of  the  edit  pointer.  The 
edit  pointer  position  does  not  change. 

1  I  ENTER  I 

displays  the  current  line.  If  the  edit  pointer  is 
not  at  the  beginiung  of  the  line,  qnjy  the  por- 
tion of  the  line  to  tie  rij^  of  tim  elifc  pmnter 
shows  (HI  the  screen. 

13  I  ENTER  I 

displays  the  current  line  and  the  next  two 
lines. 

1*  I  ENTER  I 

displays  all  text  from  the  current  position  of 
the  edit  pointer  to  the  end  of  the  buffer. 

The  L  command  displays  text  regardless  of 
which  verify  mode  is  in  effect. 

Xn  Displays  the  n  lines  that  precede  the  edit 

pointer.  The  position  of  the  edit  pointer  does 
not  change.  For  example: 

X  1  ENTER  I 

displays  any  text  on  the  current  line  that  pre- 
cedes the  edit  pointer.  If  the  edit  pointer  is  at 
the  beginning  of  the  line,  the  command  dis- 
plays nothing. 

x3  I  ENTER  I 

displays  the  two  preceding  lines  and  any  text 
on  the  current  line  that  precedes  the  edit 
pointer. 

The  X  command  displays  text  regardless  of 
which  verify  mode  is  in  effect. 
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Manipulating  the  Edit  Pointer 

rcml  (T]  or  [T]  Moves  the  edft  pdlitei'  to  the  bigfimfttg  Cttrst 
on  an  external  character)  of  the  text  buffer.  The  screen  shows 
terminal  the  up  arrow  when  you  hold  down  |  ctrl  |  and 

press  (T).  For  example, 

rCTBL]  |Tj  I  ENTER  I 

moves  the  edit  pointer  to  the  beginning  of  the 
buffer. 

/  Moves  the  edit  pointer  to  the  end  (last  charac* 

t«?  of  the  btiflfffl-:  ii  sample, 

/  I  ENTER  I 

moves  the  edit  pointer  past  the  end  of  the 
buffer. 

I  ENTER  I  Moves  the  edit  pointer  to  the  beginning  of  the 

next  line  and  displays  it.  Use  this  command  to 
go  through  text  liiie  ttt  a  time.  You  can 
look  at  each  line,  correct  any  mistafees,  and 
then  move  to  the  next  line. 
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+  n  Moves  the  edit  pointer  either  to  the  end  of  the 

line  or  forward  n  lines  and  displays  the  line. 
Entering  a  value  of  zero  moves  the  edit  pointer 
to  the  end  of  the  cmrent  line.  Ibr  example: 

+  0  l  ENTEB  I 

Entering  a  value  other  than  zero  moves  the 
pointer  forward  n  lines  and  displays  the  line. 
Eor  examplej 

+ 1  mm  I 

moves  the  pointer  to  the  next  line  and  displays 
the  line.  This  command  performs  the  same 
function  as  I  EWEM  l. 

♦1  d  mm  I 

moves  the  pointer  ahead  10  lines  and  displays 
the  line. 

+« ifiiin 

moves  the  edit  poiatar  to  the  end  of  the  bi&r. 

-n  Moves  the  edit  pointer  either  to  the  beginning 

of  the  line  or  backward  n  lines.  Ear  example: 

-0  I  ENTER  I 

moves  the  edit  pointer  to  the  beginning  of  the 
line  and  displays  the  line.  Entering  a  value 
other  than  zero  moves  the  edit  pointer  back  n 
%nm.  ibr  example, 

-  I  ENTER  I 

moves  fb®  ifit  pointer  back  one  line  and  dis- 
plays the  line. 

moves  the  edit  pointed  back  fivB  lines  and  dis- 
plays the  line. 

-»  I  ENTER  I 

moves  the  edit  pointer  to  the  beginning  (top) 
of  the  buffer  and  displays  the  first  line. 
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yjl  Moves  the  edit  pointer  to  the  right  n  charac- 

ters. Use  this  command  to  move  the  edit 
fdmfei'  to  sojEW  pMtiaa  in  &e  line  other  than 
the  first  EtecsBeter,  Bbr  e^ssLxni^e, 

>  [mm  I 

moves  the  edit  pointer  to  the  right  one 
character. 

>25  I  ENTER  | 

moves  the  edit  pointer  to  the  right  25 
characters. 

>*  I  ENTER  I 

moves  the  edit  pointer  to  the  end  of  the  buffer, 

<n  Moves  the  edit  pointer  to  the  left  n  characters. 

Use  this  eomnaand  to  nw^e  the  edit  pointer  to 
some  posltiott  in  a  liwe  ether  than  the  first 
character.  Sbr  example: 

<  I.  ENTEH I 

moves  the  edit  pointer  to  the  left  one 
character. 

< 1  0  I  ENTER  I 

moves  the  edit  pointer  to  the  left  10 
characters. 

<♦  [ENTBRI 

moves  the  edit  pointer  to  the  beginning  of  the 
buffer. 
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Inserting  and  Deletiug  Lines 

Utesst  Preceding  test  lines  wltli  a  space  inserts  the 

text  as  a  new  line  ahead  of  the  edit  pointer. 
The  position  of  the  edit  pointer  does  not 
change.  Ibr  example, 

Dlnsert  this  1 i ne  [Wfm\ 

inserts  the  line. 

□  Line  one  [  ENTER  | 
□Line  two  |  ENTER  | 
DLine  thpee  |  ENTER  | 

inserts  three  lines. 

la  str  Inserts  a  line  of  h  copies  of  the  specified  stfittg 

immediately  before  the  position  of  the  edit 
pointer.  The  position  of  the  edit  pointer  does 
not  change.  Ibr  example, 

i4^/*/  I  ENTER  | 

inserts  a  line  containing  40  asterisks.  You  can 
also  use  the  "I"  command  to  insert  a  line  con- 
taining a  single  copy  of  the  striiig.  This  ftmc- 
tion  is  important  when  you  want  to  use  a 
macro  to  insert  lines,  since  the  space  bar  can- 
not be  used  within  a  macro.  Pbr  example, 

i»'Lin,e  to  insert"  [eMTER  | 

inserts  the  line. 
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Tin  Deletes  (removes)  n  lines  from  the  edit  buffer, 

starting  with  the  Gurmnt  line.  This  command 
displays  the  lines  \a  )m  lifted.  Ib¥  Sample: 

d  I  ENTER  I 

deletes  the  etm-@£i^  line,  regardlei^  (£  the  posi- 
tion of  the  edit  pointer,  and  displays  it. 

d4  I  ENTER  | 

deletes  the  current  line  and  the  next  three 
lines. 

d«  I  ENTER  I 

deletes  everything  from  the  current  line  to  the 
end  of  the  buffer. 

Kn  Kills  (deletes)  n  characters,  starting  at  the 

curr^t  position  of  the  edit  pointer.  This  com- 
mand displays  all  del^td  characters.  For 
example, 

k  I  ENTER  I 

deletes  the  charact^  at  the  edit  pointer. 

k4  I  ENTER  | 

deletes  the  character  at  the  current  position  of 
the  edit  pointer  and  the  next  three  characters. 

k  «  I  ENTER  I 

deletes  everything  from  the  current  position  of 
the  edit  pointer  to  the  end  of  the  buffer. 
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Eb  siir  Extends  n  lines  by  adding  a  string  to  the  end 

of  each  Une.  E  extends  a  line,  displays  it,  and 
then  moves  the  pointer  past  it.  Fbr  example, 


e/thiS  is  a  convutent/  I  ENTER  I 


adds  the  string  "this  is  a  comment"  to  the  end 
of  the  current  line  and  moves  the  edit  pointer 

to  the  next  line. 


e3/xx  I  ENTER  I 


adds  the  string  xx  to  the  end  of  the  current 
line  and  the  next  two  lines.  It  moves  the 
pointer  past  these  lines. 

V  Ungxtends  (tjeletes)  the  remainder  of  &  liM 

from  the  current  posffct  rftha  pointer.  Use  D 
to  remove  extensions,  such  as  comments,  from 
a  line.  For  example. 


u  ENTER 


deletes  all  the  characters  from  the  current 
position  of  the  pointer  up  to  the  end  of  the  cur- 
rent line. 

For  some  practice  in  using  the  commands  that  display  text, 
manipulate  the  edit  pointer,  and  insert  and  delete  lines,  turn  to 
Sample  Session  1  in  this  chapter. 
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Searching  and  Substituting 

Sii  string  Searches  for  the  next  n  occurrences  of  string. 

When  Edit  finds  an  occurrence,  it  displays  the 
line  and  moves  the  edit  pointer  to  the  line.  If 
Edit  does  not  find  tlie  stiix^  m  if  all  the 
occurrences  have  been  found,  the  edit  pointer 
does  not  move.  For  example, 

s/my  string/  |  ENTER  | 

searches  for  the  next  occurrence  of  "my 
string". 

s3"st  ruTig  out"  I  ENTER  I 

searches  for  the  next  three  occurrences  of 
"strung  out". 

s»/5eek   and  find/  |  ENTER  | 

searches  for  all  occurrences  of  "seek  and  find" 
between  tihe  edit  pointer  and  the  end  of  the 
text. 

Cii  stringl  Changes  the  next  n  occurrences  of  stringl  to 

string2  string2.  When  Edit  finds  stringl,  it  moves  the 

edit  pointer  past  it  and  changes  stringl  to 
stririg2,  then  it  displays  the  updated  line.  If  it 
does  not  find  stringl  it  displays  "NOT 
FOUND."  If  all  the  occurrences  have  been 
found,  the  edit  pointer  does  not  move.  For 
example, 

c/this/that/  rBffERl 

changes  the  next  occurrence  of  "this"  to 

"that". 

c2/in/out/  I  ENTER  | 

changes  the  next  two  occurrences  of  "in"  to 
"out". 

c*!5eek   and  flnd!50Ught  and 

found  !  I  ENTER  | 

changes  all  occurrences  of  "seek  and  find" 
that  are  between  the  edit  pointer  and  the  end 
of  text  to  "sought  and  fovuid". 
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An  Sets  the  SEARCH/OHANSE  anchor  to  Col- 

umn n.  To  find  a  string  that  begins  in  a  spe- 
cific column,  set  the  anchor  to  the  column 
position  before  using  the  search  command  to 
find  it.  If  you  do  not  include  a  value  for  n,  Edit 
assumes  Column  1.  Ibr  example: 

a  I  ENTER  I 

ffituis  a  string  only  if  it  he^ns  in  Column  1. 

a20  I  ENTER  I 

finds  a  string  only  if  it  begins  in  Column  20. 

If  you  use  the  A  command  to  set  the  anchor, 
this  setting  remains  in  effect  only  for  the  cur- 
rent command  line.  After  Edit  executes  the 
ecnnmand,  the  anchor  automatically  returns  to 
its  nonnai  value  of  zero  . 

Woe  some  practice  in  using  the  commandos  thai  search  and  sahsti- 
tute,  turn  to  Sample  Session  2  in  this  chapter. 

MisceUcmeous  Commands 

Tb  Tabs  (moves)  the  edit  pointer  to  Column  n  of 

the  current  line.  If  n  exceeds  the  line  length, 
this  command  extends  the  line  with  spaces. 
Wm  example, 

t  I  ENTER  I 

mov@s  the  B&i  pointer  to  G^wam  1  of  the  cur- 
rent line, 

ti  iwm\ 

moves  the  edit  pointer  to  Column  5  of  tiie  cur- 
rent line. 


7-14 


Macro  Text  Editor  I  7 


.SEDSLL  Lets  you  use  any  OS-9  command  from  within 

command  the  editor.  The  remainder  of  the  conmiand  Une 

line  blowing  .MBUi  passett  to  the  OS-9  Shell  for 

execution,  fbr  ex£unple, 

.ahjell  dtr  /d1  [mm\ 

calls  the  OS-9  Shell  to  display  the  directory  of 
Dl. 

.  shel  1   basic09  |  ENTER  | 
starts  BASIC09. 

.shell   edit    aldfile  newfile  |  ENTER  | 

restarts  the  editor. 

Mn  Adjusts  the  amount  of  memory  available  for 

buffers  and  macros.  If  the  workspace  is  full 
and  the  editor  does  not  allow  you  to  entar 
more  text,  increase  the  workspace  size.  If  you 
need  only  a  small  amount  of  the  available 
workspace,  decrease  the  workspace  size  so  that 
other  OS-9  programs  can  use  the  memory.  Fbr 
example, 

m5000  I  ENTER  | 

sets  the  workspace  size  to  5000  bjrtes. 

ml  0  0  0  0  I  ENTER  | 

sets  the  workspace  size  to  10000  bytes. 

Before  leaving  Edit,  you  can  increase  the 
workspace.  This  decreases  the  time  the  editor 
takes  to  copy  the  input  file  to  the  output  file, 
because  the  editor  can  read  and  write  more 
data  at  csae  time.  Edit  changes  memory  in 
256-byte  pages.  For  the  M  command  to  have 
any  effect,  a  new  workspace  size  must  differ 
from  the  current  size  by  at  least  256  bytes. 
The  M  command  does  not  let  you  deallocate 
any  workspace  that  Edit  needs  for  buffers  or 
macros. 
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.SIZE  Displays  the  size  of  the  workspace  and  the 

amount  that  has  been  used.  For  example: 

.size 

S21  tSlti 

521  is  the  amount  d  workspace  Edit  uses  to" 
buffers  and  macros.  15328  is  the  amount  of 

available  memory. 

Q  Ends  editing  and  returns  to  the  OS-9  Shell.  If 

you  specified  files  when  you  started,  Edit 
writes  the  text  in  Buffer  1  to  the  initial  write 
file  (specified  when  you  start  Edit).  Next  it 

copies  the  remainder  of  the  initial  input  file 
(specified  when  you  start  Edit)  to  the  initial 
write  file.  The  editor  then  terminates,  and 
control  returns  to  the  OS-9  Shell. 

Vmode  Turns  the  verify  mode  on  or  off.  Edit  always 

starts  with  the  verify  mode  en.  Therefore,  the 

editor  displays  the  results  of  all  the  commands 
for  which  verify  is  appropriate.  If  you  do  not 
tmnt  to  see  Uie  results  of  comrnands,  torn 
the  verify  mode  by  specifying  0  (zero)  for 
mode.  To  turn  verify  back  on,  specify  any  non- 
zero number.  Bbr  example, 

V0  I  ENTEH  I 

turns  off  the  verify  mode. 

v2  1  ENTER  I 

turns  on  the  verify  mode. 

v13  I  ENTER  I 

turns  on  the  verify  mode. 

If  the  verify  mode  is  on  when  you  switch  to  a 
macro,  it  remains  on.  If  you  turn  off  verify 
isAils  in  the  macro,  it  is  restored  when  you 
retuim  to  the  editor. 
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Manipulating  Multiple  BufGra's 

J)IR  Disidas^s  the  director:^  of  the  editor's  buffers 

and  majcros.  Ebr  example: 

BUFFERS: 

$         0  (secondary  buffer) 
»         1  (primary  buffer) 
5  (another  buffer) 

MACROS: 

MYMACRD 

LIST 

COPY 

Bxi  Makes  buffer  n  the  primary  buffer.  When  you 

switch  from  one  buffer  to  another,  the  old  one 
becomes  the  secondary  buffer,  and  the  new  one 
becomes  the  primary  buffer.  For  example, 


bS  I  ENTER  1 


makes  Buffer  5  the  primary  buffer.  If  Buffer  5 
does  not  exist,  Edit  creates  it. 

Pa  Puts  (moves)  n  lines  into  the  secondary  buffer. 

This  command  removes  the  lines  from  the  pri- 
mary buffer,  starting  at  the  position  of  the 
edit  pointer,  and  inserts  them  into  the  second- 
ary buffer  before  the  current  position  of  the 
edit  pointer.  It  displays  the  text  that  is  moved. 
Rnr  sample, 

p  I  ENTER  I 

moves  one  line  to  the  secondary  buffer. 


p5  I  ENTER  I 

moves  five  lines  to  the  secondary  buffer. 


p«  I  ENTER  I 

moves  all  lines  that  8U"e  between  the  current 
position  of  the  edit  pointer  and  the  end  of  text 
to  the  secondary  buffer. 
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Gh  Gets  (moves)  n  lines  from  the  secondary 

bxiffer.  This  command  takes  the  lines  from  the 
top  of  the  seconciary  buflfer  and  Inserts  ihsm 
into  the  primary  buffer  before  the  current 
position  of  the  edit  pointer.  Edit  then  displays 
the  moved  lines.  When  used  with  the  P  com- 
mand, G  moves  text  from  one  place  to  another. 
For  example, 

g  fENTERl 

gets  0H6  line  from  the  secondary  buffer. 

g5  I  ENTER  | 

gets  five  lines  from  the  secondary  buffer. 

g*  I  ENTER  1 

gets  all  lines  from  the  secondary  buffer. 

For  some  practice  in  using  miscellaneous  commands  and  the 
commands  that  manipulate  multiple  buffers,  turn  to  Sample  Ses- 
sion 3  in  this  chapter. 

Text  File  Operations 

This  section  of  the  manual  describes  the  group  of  commands 
related  to  reading  and  writing  OS-9  text  files. 

.NEW  Gets  new  text.  Use  .NEW  when  editing  a  file 

that  is  too  large  to  fit  into  the  editor's  work- 
space. .NEW  writes  out  all  lines  that  precede 
the  current  line,  then  appends  an  equal 
amount  of  new  t^  to  the  end  of  the  buiifer. 

.NEW  always  writes  text  to  the  initial  output 
file  (created  when  you  start  the  editor)  and 
always  reads  text  from  the  initial  input  file 
(specified  when  you  start  the  editor). 

If  you  have  finished  editing  the  text  currently 
in  the  buffer,  you  can  "flush"  this  text  and  fill 
the  buffer  with  new  text  by  moving  the  edit 
pointer  to  the  bottom  of  the  buffer  and  then 
using  the  .NEW  command.  Ibr  aample: 

/  .new  I  ENTER  I 
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If  you  wish  to  retain  part  of  the  text  that  is 
already  in  the  buffear,  move  the  edit  pointer  to 
the  first  line  you  vsish  to  I'etalfi  and  then  type 
.new.  This  command  "flushes"  all  lines  that 
precede  the  edit  pointer.  It  then  tries  to  read 
in  new  text  that  is  the  same  size  as  the  por- 
tion flushed  out. 

.READ  str         Prepares  an  OS-9  text  file  for  reading,  str 
specifies  the  pathlist.  For  example. 

.read  "myf  lie"  |  ENTER  | 

closes  the  current  input  file  and  opens 
"myfile"  for  reading. 

You  can  specify  an  empty  pathlist.  For 

example, 

.read   ""  |  ENTER  | 

closes  the  current  input  file  and  restores  the 
initial  input  file  (specified  when  you  start  the 
editor)  for  reading. 

An  open  file  remains  attached  to  the  primary 
buffer  until  you  close  the  file.  You  can  have 
more  than  one  input  file  open  at  any  time  by 
using  the  .READ  command  to  open  them  in 
different  buffers. 

lb  read  these  files,  swfteh  to  the  prefer  bufifer, 
and  then  use  the  R  command  to  read  from 
that  buffer's  input  file.  To  close  a  file,  you 
must  be  in  the  same  bxiffer  where  the  file  was 
opened. 
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•WRITE  Sti"  Opens  a  new  file  for  writing.  The  string  speci- 
fies the  pathlist  for  the  file  you  wish  to  create. 
Ite  example, 

.write  "newf  ile"  |  ENTER  | 

closes  the  current  write  file  and  creates  one 
called  "newfile".  You  can  specify  an  empty 
pathlist.  For  example: 

.write   ""  I  ENTER  | 

closes  the  current  write  file  and  restores  the 
initial  write  file  (specified  when  you  start  the 

editor). 

•WRITE  attaches  a  new  write  file  to  the  pri- 
mary buffef  that  remains  attached  until  you 

close  the  file.  You  can  have  more  than  one 
write  file  open  by  using  .WRITE  to  open  them 
in  dfflbent  trtrffe.  Ife  write  these  files,  ##it4!ih 
to  the  proper  buffer.  To  close  a  file,  you  must 
be  in  the  same  buffer  where  the  file  was 
opened. 

Rn  Reads  (gets)  n  lines  of  text  from  the  buffer's 

input  file.  It  displays  the  lines  and  inserts 
them  before  the  current  position  of  the  edit 
pointer.  Fbr  example, 

r  [EITO,|: 

reads  one  line  from  the  input  file. 

r1  0  .1  ENTEP 1 
reads  10  lines  from  the  input  file. 

r*  I  ENTER  I 

reads  the  remaining  lines  ftam  the  input  file. 

If  a  file  contains  no  more  text,  the  screen 
shows  the  *END  OF  FILE*  message. 
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Wn  Writes  n  lines  to  the  output  file,  starting  with 

the  current  line.  It  displays  all  lines  that  are 
deleted  fmm  tlie  biaffa".  ftir  ©sirople, 

w  l  ENTEfl  l 

writes  the  current  line  to  the  output  file, 
w  S  I  ENTER  I 

writes  the  current  line  and  the  next  foxir  lines 
to  the  output  file. 

w*  I  ENTER  I 

writes  all  lines  from  the  current  line  to  the 
end  of  the  buffer  to  the  output  file. 

For  some  practice  in  using  the  commands  that  read  and  write 
OS-9  text  files,  turn  to  Sample  Session  4  in  this  chapter. 

Conditionals  and  Command  Series  Repetition 

When  a  command  cannot  be  executed,  the  editor  sets  an  internal 
flag,  and  the  screen  shows  *FAIL*.  For  example,  if  you  try  to 
read  from  a  file  that  has  no  more  text,  the  editor  sets  the  fail 
flag.  A  set  fail  flag  means  that  the  editor  cannot  execute  any 
more  commands  until  Edit  encounters  one  of  the  following: 

•  The  end  of  a  command  line  typed  from  the  k^board. 

•  The  end  of  the  current  loop.  Any  loops  that  are  more 
deeply  nested  are  skipped.  (See  the  repeat  command.) 

•  A  colon  (:)  command.  Since  loops  nested  deeper  than  the 
flfflRegftt  level  are  skipped,  any  occurrences  of  :  that  are 
in  a  more  deeply  nested  loop  are  also  skipped. 
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Ebllowing  are  the  commands  and  conditions  that  set  the  fail  flag: 


<  Trying  to  move  the  edit  pointer  beyond  the 

beginning  of  the  edit  buffer. 

>  Trying  to  move  the  edit  pointer  beyond  the  + 

end  of  the  buffer. 

S,C  Not  finding  a  string  that  was  searched  for. 

G  No  text  left  in  the  secondary  buffer. 

R  No  text  left  in  the  read  file. 

P,W  No  text  left  in  the  primary  buffer. 


If  you  specify  an  asterisk  for  the  repeat  count  on  these  com- 
mands, Edit  does  not  set  the  fail  flag,  because  an  asterisk  usu- 
ally means  continue  until  there  is  nothing  more  to  do.  The 
following  commands  explicitly  set  the  fail  flag  if  some  condition 
is  not  true. 

.EOF  Tests  for  end-of-file.  .EOF  succeeds  if  there  is 

no  more  text  to  read  from  a  file.  Otherwise,  it 
sets  the  fail  flag. 

.NEOF  Tests  for  not  end-of-file.  .NEOF  succeeds  if 

there  is  text  to  read  from  the  file.  Otherwise, 
it  sets  the  fail  flag. 

.EOB  Tests  for  end-of-buffer.  .EOB  succeeds  if  the 

edit  pointer  is  at  the  end  of  the  buffer.  Other- 
wise, it  sets  tlie  fail  flag. 

.NEOB  Tests  for  not  end-of-buffer.  .NEOB  succeeds  if 

the  edit  pointer  is  not  at  the  end  of  the  buffer. 
Otherwise,  it  sets  the  fail  flag. 

.EOL  Tests  for  end-of-line.  This  test  succeeds  if  the 

edit  pointer  is  at  the  end  of  the  line.  Other- 
wise, it  sets  the  fail  flag. 

.NEOL  Tests  for  not  end-of-line.  .NEOL  succeeds  if 

the  edit  pointer  is  not  at  the  end  of  the  line. 
Otherwise,  it  sets  the  fail  flag. 

.ZERO  n  Tests  for  zero  value.  .ZERO  succeeds  if  n 

equals  zero.  Otherwise,  it  sets  the  fail  flag. 
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.STAR  jQ 


.STB  stt 


.NSTR  str 


.S 


.F 


[comxtmBiisli^ 


Tests  for  star  (asterisk).  .STAR  succeeds  if  n 
equals  65,535  ("*").  Otherwise,  it  sets  the  fail 
flag. 

Tests  for  string  mateli.  .STR  succeeds  if  the 
characters  at  tiif  earrent  position  of  the  edit 
pointer  naafeii  tibg  striu®.  Otibirwf ae,  it  sete 
the  fail  flag. 

Tests  for  string  mismatch.  .NSTR  succeeds  if 
the  characters  at  the  current  position  of  the 
edit  pointer  do  not  match  the  string.  Other- 
wise, it  sets  the  fail  flag. 

Exits  and  succeeds.  This  is  an  unconditional 
exit  from  the  innermost  loop  or  macro.  The 
fail  flag  clears  after  the  exit. 

Exits  and  fails.  This  is  an  unconditional  exit 
from  the  innermost  loop  or  macro.  The  fail 
flag  gets  after  the  exit. 

Repeats  the  commands  n  times.  Left  and  right 

brackets  form  a  loop  that  repeats  the  enclosed 
commands  n  times.  (The  loop  must  be 
repeated  at  least  once.)  If  you  enter  the  loop 
command  from  the  keyboard,  it  must  all  be  on 
erne  line.  If  if  is  pert  of  m  mmta,  hropw,  it 
can  span  se*^§l  awamatid  lines.  For  escample, 


[1]  5  UnteFI 


repeats  the  L  command  five  times. 

Note:  This  is  not  the  same  as  L5,  which  executes  the  L 
command  only  once  and  has  5  as  its  parameter. 


[  +  ]* 


Displays  lines  starting  with  the  next  line  up 
to  the  end  of  the  buffer  and  moves  the  edit 
pointer  to  the  end  of  the  buffer. 

This  command  repeats  until  the  operation 
readies  the  end  of  the  buffer,  tten,  when  the 
command  tries  to  move  the  edit  pointer  past 
the  end  of  the  buffer,  Edit  sets  the  fail  flag, 
terminates  the  loop,  then  clears  the  fail  flag. 
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:  commands  Executes  the  commands  following  the  colon 
based  on  the  state  of  the  fail  flag.  For 
example: 

FAIL  FLAG  CLEAR  Skips  all  commands 
that  follow  the  colon  (:) 
up  to  the  end  dt  cur- 
rent loop  or  macro. 

FAIL  FLAG  SET  Clears  the  fail  flag,  and 
executes  the  commands 
that  follow  the  colon  (:). 

Below  is  a  command  line  that  deletes  all  lines 
that  do  not  begin  with  the  letter  A. 

rCTRLlIT]  [    .neob   [    .3tr"A"  +    :  d  ] 
]   «  I  ENTER  I 

H  moves  the  edit  pointer  to  the  beginning  of 
the  buffer.  The  outer  loop  tests  for  the  end  of 
the  buffer  and  terminates  the  loop  when  it  is 
reached. 

The  inner  loop  tests  for  A  at  the  beginning  of 
the  line.  If  there  is  an  A,  the  +  command  is 
executed.  Otherwise,  it  executes  the  D 
command. 

Below  is  a  command  that  searches  the  current 
line  for  "find  it".  If  the  command  finds  the 
text,  it  displays  the  line.  Otherwise,  the  com- 
mand line  fails  and  the  screen  shows 

•  FAIL  ». 

[  .eol  v0  -0  V  .f  :  .5tr"find  it" 
-0    .5    :    [>]    ]•  I EWTEB  | 

.EOL  VO  -0  V  .F  tests  to  determine  if  the  edit 
pointer  is  at  the  end  of  the  line.  If  it  is,  Edit 
turns  off  the  verify  mode  to  prevent  -0  from 
displaying  the  line.  Then  it  turns  verify  back 
on,  and  .F  ends  the  loop. 
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If  the  edit  pointer  is  not  at  the  end  of  the  line, 
the  .STR  command  searches  for  "find  it"  at  the 
emrrent  positto  of  the  edit  pointer.  If  it  is  at 
the  end  of  the  line,  Edit  executes  the  -0  .S 
commands.  This  execution  moves  the  edit 
pointer  back  to  the  beginning  of  the  line,  dis- 
plays the  line,  and  terminates  the  loop.  Other- 
wise, the  >  command  moves  the  edit  pointer 
to  the  next  position  in  the  line. 

The  brackets  prevent  the  command  from  fail- 
ing and  terminating  the  main  loop  if  the  end 
of  the  buffer  is  reached. 

Edit  Macros 

Edit  macros  are  commands  you  create  to  perform  a  specialized 
or  complex  task.  For  example,  you  can  replace  a  frequently  used 
series  of  commands  with  a  single  macro.  First,  save  the  series  in 
a  macro.  Then  each  tiine  you  need  it,  type  a  period  followed  by 
the  macro's  name  and  parameters.  The  editor  responds  as  if  you 
had  typed  the  series  of  commands. 

Macros  consist  of  two  main  parts,  the  header  and  the  body.  The 
header  gives  the  macro  a  name  and  describes  the  type  and  order 
of  its  parameters.  The  body  consists  of  any  number  of  or^inaEy 
commands.  (Except  for  a  space  character  and  I  enter  1,  you  can  vm 
any  command  in  a  macro). 

Note:  Macros  cannot  create  new  macros. 

To  create  a  macro,  first  define  it  with  the  .MAC  command.  Then 
enter  the  header  and  body  in  the  same  manner  as  you  enter  text 
into  an  edit  buffer.  When  you  are  satisfied  with,  the  macro,  ctose 
its  definition  by  pressing  (J]  |  enter  |.  This  command  returns  you 
to  the  normal  edit  mode. 

Macro  Headers.  A  macro  header  must  be  the  first  line  in  each 
macpo.  It  consists  of  a  name,  and  a  *VariaWB  list"  that  describes 
the  macro's  parameters,  if  there  are  any.  The  name  consists  of 
any  number  of  consecutive  letters  and  underline  characters.  Fol- 
lowing are  possible  macro  names: 

del-all 

trim_spaces 

LIST 

CHANGE_X_TO_Y 
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Although  you  can  make  a  macro  name  any  length,  it  is  better  to 
keep  it  short,  because  you  must  spell  it  the  same  way  each  time 
you  use  it.  You  cam  use  upper-  and  lowercase  letters  or  a 
mixture. 

Using  Macros.  Like  other  commands,  you  can  give  parameters 
to  m£u;ros  so  that  they  are  able  to  work  with  different  strings 
and  with  diffe etlt  ntittibeif^  of  items.  Macws  are  unable  to  use 

parameters  directly.  Instead,  Edit  passes  the  parameters  on  to 
the  commands  that  make  up  the  macro. 

To  pass  the  macro's  parameters  to  these  commands,  use  the 
variable  list  in  the  macro  header  to  tell  each  command  which  of 
the  macro's  parameters  to  use.  Each  variable  in  the  variable  list 
represents  the  value  of  the  macro  parameter  in  its  corresponding 
position.  Use  the  corresponding  variable  wherever  the  parame- 
ter's value  is  needed. 

The  two  types  of  variables  are  numeric  and  string.  A  numeric 
variable  is  a  variable  name  preceded  by  the  #  character.  A 
string  variable  is  a  variable  name  preceded  by  a  $  character. 
Variable  names,  like  macro  names,  are  composed  of  any  number 
of  consecutive  letters  and  underline  characters.  Examples  of 
numeric  variables  are: 

#N 
#ABC 

#L0NGJ^U1[BEIL-VARIABLE 

Examples  of  string  variables  are: 

$A 
$B 

$STR 
$STR_J^ 

$lower_case_variable_name 

The  fUnctkm  of  the  edit  macro  Wow  &  fte  aaiHe  « limt  of  the  S 
command,  to  search  for  the  natt  n  occurrences  of  a  string. 
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The  first  line  of  the  macro  is  the  macro  header.  It  assigns  the 
macro's  name  as  SRCH.  It  also  specifies  that  the  macro  needs 
one  TMitneric  parameter  and  one  string  parameter  ($^fll). 
The  entire  body  of  the  macro  is  the  second  line.  This  example 
passes  both  of  the  macro's  parameters  to  the  S  command,  which 
does  the  actual  searching. 

SRCH  #N  *STR 
S  *N  tSTR 

Here  is  an  example  of  how  to  execute  this  macro: 

.  SRCH   1  B  "string"  |  ENTER  | 

In  the  next  example,  the  order  of  the  parameter  is  reversed. 
Thi^el^re,  vAsso.  e^uting  the  macro,  use  the  reverse  order.  The 
macro  structure  is: 

SRCH   $STR  *N 
S  #N  $STR 

Specify  the  parameters  for  the  "S"  command  in  the  proper  order 
since  it  is  only  the  "SRCH"  macro  that  is  changed.  TSie  following 
example  shows  how  to  execute  this  macro.  The  order  of  the 
parameters  corresponds  directly  to  the  order  of  the  variables  in 
the  variable  list. 

.SRCH  "string"  1  5  |  ENTER  | 
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Macro  Commands 

Although  macro  editing  has  the  same  functions  as  text  editing, 
the  macro  mode  also  includes  some  special  commands.  The 
mmm  mmmum'SM  yoa  tiii         ii  f0lte«is( 

!  text  Places  comments  inside  a  macro.  Ignores  the 


remainder  of  the  line  following  the  !  command. 
This  command  lets  you  include,  as  part  of  a 
macro,  a  short  description  of  what  it  does. 
Comments  can  help  jou  remember  the  func- 
tion of  a  mmto.  Ibr  ^ffioa^: 


.macro  name      Executes  the  macro  specified  by  the  name  fol- 
lowing the  period  (.).  For  example: 


<*>!  Move  the  pointer  to  the  top  of  the 
buffer. 

1*!      Display  all  lines  of  text. 


In  this  example  there  are  four  comments.  Two 
are  empty,  and  two  feerifee  the  commands 
that  precede  them. 


.mymacro  |  ENTER  | 


.list  0  I  ENTER  I 


.  trim  "  "  I  ENTER  | 


.merge  "  f  i  1  e_a  "   file  b  b"  |  ENTER  | 


.MAC  str 


.mac""  I  ENTER  I 

creates  a  mm  macro  and  puts  jm  into 
macro  mode. 
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The  screen  shows  M:  instead  of  E:  when  the 
editor  is  in  the  macro  mode.  To  edit  a  macro 
l^t  alrm%  e^ts,  spm%  the  macro's  name. 
Ear  example, 

.mac  "iHj^macre"  1  PTtB I 

opens  the  vamm  '*MYIttlCBO"  eiitjjc^* 

When  a  macro  is  open,  edit  it,  or  enter  its  def- 
inition with  the  same  commands  you  use  in  a 
text  buffer.  After  you  edit  the  macro,  press  (T) 
I  ENTER  I  to  close  its  definition  and  return  to  the 
edit  mode.  The  first  line  of  the  macro  must 
begin  with  a  name  that  is  not  already  used  in 
order  to  close  the  definition  and  return  to 
Edit. 

•SAVE  atrl  Saves  macros  on  an  OS-9  file.  Strl  specifies  a 
str2  list  of  macros  to  be  saved.  Separate  the  macro 

names  with  spaces.  Str2  specifies  the  pathlist 
for  the  file  on  which  you  want  to  save  the 
macros.  For  example: 

.save   "mvmacro"myfile"  |  ENTER] 

saves  the  macro  "MYMACRO"  on  the  file 
"MYFILE". 

.save  "maca  macfa  macc"mfile"  flNTER  | 

saves  the  macros  "MACA,"  "MACB,"  and 
"MACC"  on  the  file  "MFILE". 

Searches  the  text  file  buffer  for  the  specified 
string.  When  a  match  is  found,  it  stops  and 
displays  that  line.  The  n  option  permits  a 
search  for  the  nth  occurrence  of  a  string 
match.  This  command  is  the  same  as  S  n  str. 


•SEARCH  n 
str 
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.LOAD  sir 


.DEL  str 

.DIR 
strl  str2 


Loads  macros  from  an  OS-9  file.  As  each 
macro  loads.  Edit  verifies  that  no  other  macro 
already  exists  with  the  same  name.  If  one 
does,  the  macro  with  the  duplicate  name  does 
not  load,  and  Edit  skips  to  the  next  macro  on 
the  file.  Edit  displays  the  names  of  all  macros 
it  loads.  Eeit  sample, 

.load  "macrof  lie"  [ENTER  | 

loads  the  macros  in  the  file  called 
MACROFILE. 

.  load   "myf  i  le"  |  ENTER  | 

loads  the  macros  in  the  file  called  MYFILE. 

Deletes  the  macro  specified  by  the  string.  For 
example, 

.del  "tnymacro"  | ENTER | 

deletes  the  macro  called  MYMACBO. 

.del  "list"  I  ENTER  I 

deletes  the  macro  called  LIST. 

Displays  the  current  edit  buffer  area.  All  edit 
buffers  and  macros  currently  in  memory  are 


Ohaiiges  ihe  oectuT^Oi^  of  strl  to  str^.  The  n 
option  permits  n  occurrences  of  sirl  to  be 
changed  to  str2. 
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Q 


Ends  a  macro  edit  session  and  returns  yoa  to 
the  normal  edit  mode.  For  example: 

Search_and_Delete  #N  $STR 
!This  example  MACRO  is  used  to 
! efeeek 

•the  string  at  the  beginniTig  of 
!an  #N   number   of    lines.    If  the 
[string  matches,    it   will  delete 
Jtftat  line  frpm  the  text  buffer 
if  lie. 


!  NOTE :    The   way   the  editor 
(processes  a  MACRO  causes   it  to 
f see  any  parameters  In  the  outer 
lloop  first.    Thus,    the  #N 
Iparameter    is   processed  before 
! the  SIR  parameter. 


C 


,  neob 
[ 

.natr  fstr 


3 


Move  to  start  of 
edit  buffer 
start  of  outer  loop 
test  for  buffer  end 
start  of  innef  loop 
test  for  not  string 
ma  t  c  h 

go  to  next   line  if 
no  match 

if  flag  clear  skip 
next  command 
delete  line  if  flag 
set 

end  of  lB:fter  loop 
eind  of  outer  loop 


End  of  Macro 


Fbr  practice  in  using  macro  commands,  turn  to  Sample  Session  5 
in  this  chapter. 
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Sample  Session  1 

Clear  the  buffer  by  deleting  its  contents. 

You  Type:  rcTRLllTI  D*  I  enter  | 

Screm  Shows:  *  D  • 

Insert  three  lines  into  the  buffer.  Begin  each  line  with  a  space, 

which  is  the  command  for  inierting  text. 

TfouType:  OTY  FIRST  LIHE  [InterI 

□MY  SECOND  LINE  UnTERI 
QMY  THIRD  LINE  |  ENTER  | 

Screen  Shows:         my  first  line 

MY  SECOND  LINE 
MY  THIRD  LINE 

Move  the  edit  pointer  to  the  top  of  the  text.  The  editor  always 
considers  the  first  character  you  type  a  command. 

Note:  I  CTRL  |(T1  always  shows  "  on  the  screen.  Typing  -  •  also 
moves  the  edit  pointer  to  the  beginning  of  a  buffer, 
l&n  Type;  fUnffl  fWfERl 

List  (display)  the  first  line  you  inserted  into  the  buffer. 
You  Type:  L  |  enter  | 

Screen  Shows:  L 

MY  FIRST  LINE 

Display  the  first  two  lines  you  inserted  into  the  buffer. 
You  Type:  L2  |  enter  | 

Screen  Shows:  L2 

MY  FIRST  LINE 
MY  SECOND  LINE 

Move  to  the  next  line  and  display  it. 
You  Type:  I  enter  I 

B&m&&&l(mm  MY  SECOND  LINE 

It&ve  to  the  next  line  and  display  it. 
You  Type:  I  enter  | 

Screen  Shows:  MY  THIRD  LINE 
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Using  L,  display  text  beginning  at  the  position  of  the  edit 
pointer.   

ia»u  Type:  L  ^mm\ 

Screen  Shows:  L 

MY  THIRD  LINE 

Insert  a  line  into  the  buffer. 

Note:  In  the  next  sample  you  see  that  the  insert  comes 
before  the  current  position  of  the  edit  pointer. 

You  Type:  DINSERT  A  line  | enter  | 

Scx^m  Shows:         insert  a  line 

The  following  command  line  consists  of  more  than  one  command. 

rcTRTIfn  I  ENTER  |  moves  the  edit  pointer  to  the  top  of  the  text.  L  dis- 
plays the  text,  and  the  asterisk  ( » )  following  L  indicates  that  text 
is  displayed  through  to  the  end  of  the  buffer. 

You  Type:  [CTRLUnL*  [enter  | 

Screen  Shows:  *L» 

MY  FIRST  LINE 
MY  SECOND  LINE 
INSERT  A  LINE 
MY  THIRD  LINE 

Show  the  position  of  the  edit  pointer. 
You  Type:  L  |  enter  | 

Screen  Shows:  L 

MY  FIRST  LINE 

Move  the  edit  pointer  forward  two  lines  and  display  the  lines. 
"Sbul^e:  *2  \  mm  \ 

Screen  Shows:  *  2 

INSERT  A  LINE 

Display  all  lines  from  the  edit  pointer  to  the  end  of  the  buffer. 
You  Type:  L  »  |  ENTER  I 

Screen  Shows:  L* 

INSERT  A  LINE 
MY  THIRD  LINE 

Move  the  edit  pointer  to  the  end  of  the  buffer. 
You  Type:  /  |  enter  | 

Screen  Shows:  / 

Determine  if  the  edit  pointer  is  at  the  end  of  text.  Since  the 
screen  shows  no  more  lines,  the  edit  pointer  is  at  the  end-of-text. 
"Sfett  Ty^et  L»  I  ENTER  I 

Screen  Shows:  L* 
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Insert  two  more  lines. 

You  Type:  OFIFTH  LINE  |  ENTER] 

DLAST  L«E  fiMTERl 

Screen  Shows:  F  i  fth  L  t  Hi 

LAST  LINE 

!&l^e  the  edit  pdnter  Mck  one  line,  and  display  the  Ite. 
You  Type:  -  2  |  enter  1 

Screen  Shows:  -  2 

FIFTH  LINE 

Move  the  edit  pointer  back  tvvo  lines,  and  display  the  line. 
You  Type:  -.3  |  enter  ! 

Screen  Shows:  -3 

MY  SECOND  LINE 

Move  the  edit  pointer  three  characters  to  the  right  and  display 

the  remainder  of  the  line. 

Note:  You  must  put  spaces  between  commands. 
You  Type:  >'3  L  [eiTORl 

Screen  Shows:  >  3  L 

SECOND  LINE 

Display  the  characters  that  precede  the  edit  pointer  on  the  cur- 
rent line. 

You  Type:  x  I  enter  | 

Screen  Shows:  X 

Move  the  edit  pointer  to  the  end  of  the  current  line. 
You  Type:  +  0  I  enter  | 

Screen  Shows:  +  0 

Determine  if  the  edit  pointer  is  at  the  end  of  the  line.  It  is,  since 
the  screen  shows  no  lines. 

Ym.  Type:  L  I  enter  | 

Screen  Shows:  L 

Display  the  characters  that  precedie  the  edit  pointer  on  the  cur- 
rent line. 

You  Type:  X  |  ENTER  | 

Screen  Shows:  X 

MY  SECnND  LINE 
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M)ve  the  edit  pointer  back  to  the  beginning  of  the  current  line. 
You  Type:  -  0  I  enter  | 

Screen  Shows:  -  0 

MY  SECOND  LINE 

Determine  if  the  edit  pointer  is  at  the  beginning  of  the  line. 
Since  the  screen  shows  no  lines,  the  pointer  is  at  the  beginning. 

You  type:  X  I  enter  | 

Screen  Shows:  X 

Go  to  the  beginning  of  the  text. 
You  Type: 
Screen  Shows: 


fCTRUHn  I  ENTER  | 


Insert  a  line  of  14  asterisks. 
You  Type: 
Screen  Shows: 


I  14"*"  I  ENTER  I 
I14"»" 
«•••#••«»•«##« 


Insert  an  empty  line. 
You  Type: 
Screen  Shows: 


I""  I  ENTER  I 
I 


Move  to  the  top  of  the  text,  and  display  all  lines  in  the  buffra*. 
You  Type:  ["ctrlKTIl*  | enter] 

Screen  Shows:  *L» 


••#•••••••••«• 

MY   FIRST  LINE 
MY   SECOND  LINE 
INSERT  A  LINE 
MY  THIRD  LINE 
FIFTH  LINE 
LAST  LINE 


Move  the  edit  pointer  forward  two  lines. 
You  Type:  +  2  |  enter  | 

Screen  Shows:  +  2 


Extend  the  line  with  XXX. 
You  Type; 
Screen  Shows: 


MY  FIRST  LINE 


E"   XXX"  I  ENTER  | 
E"  XXX" 
MY  FIRST  LINE  XXX 


Display  the  current  line. 
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Note:  The  previous  E  command  mioved  the  edit  points  to 
the  next  line. 

■Ybu  Type:  L  |  enter  | 

Screen  Shows:  L 

MY  SECOND  LINE 

Extend  three  lines  with  YYY. 

IfouType:  E3"DYYY"  flNTEBl 

Screen  Shows:         E3"  YYY" 

MY  SECOND  LINE  YYY 

INSERT  A  LINE  YYY 
MY  THIRD  LINE  YYY 

Move  back  2  lines. 

15m Type:  -2  | enter] 

Screen  Shows:  -2 

INSERT  A  LINE  YYY 

Move  the  edit  pointer  to  the  end  of  the  line  and  then  move  the 
edit  pointer  back  four  characters.  Display  the  ciirrent  line,  start- 
ing at  the  edit  pointer. 

"SbuType:  +0  <4  L  | entert 

Screen  Shows:         +0  <  4  L 

YYY 

Truncate  the  line  at  the  current  position  of  the  edit  pointer.  This 
CCfflomand  removes  the  YYY  extension. 

You  Type:  u  I  enter  I 

Screen  Shows:  U 

INSIRT  ft  LINE 

Go  to  the  top  of  the  text  and  display  the  contents  of  the  buffer. 
You  Type:  fCTRLlIT]  L*  |  enter  | 

Screrai  Shows:  *L« 

************** 

MY  FIRST  LINE  XXX 

MV  SECDND  LINE  YYY 

INSERT  A  LINE 

MY  THIRD  LINE  YYY 

FIFTH  LINE 

LAST  LINE 
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Delete  the  current  line  and  the  next  line. 
ISju  Tjrpe:  D2  |  enter  | 

Screen  Shows:  D2 


Move  the  edit  pointer  forward  two  lines. 
Tfou  Type:  +  2  [  EHTtfl  l 

Screen  Shows:  +2 


INSERT  A  LINE 


Delete  this  line. 

You  Type:  D  |  ENTER  | 

Screen  Shows:  D 


INSERT  A  LINE 

Difpla^  the  current  line. 

You  Type:  L  faiTERl 

Screen  Shows:  L 

MY  THIRD  LINE  YYY 

Move  the  edit  pointer  to  the  right  three  characters  and  display 
the  text. 

Tibu  Type:  >3  L  |  enter  | 

Screen  Shows:  >  3  L 

third  line  YYY 

Kill  (delete)  the  11  characters  that  constitute  THIRD  LINE. 
You  Type:  K 1 1  I  enter  | 

Screen  Shows:  K1 1 

THIRD  LIME 

Go  to  the  beginning  of  the  line  and  display  il. 
You  Type:  -  0  |  ENTER  | 

Screen  Shows:  -  0 

MY  YYY 

Concatenate  (combine)  two  lines.  Move  the  edit  pointer  to  the 
end  of  the  line;  delete  the  character  at  the  end  of  the  line;  move 
the  edit  pointer  back  to  the  beginning  of  the  l&es.  Display  the 
line. 

You  Type:  +  0  K  -  0  I  enter  | 

Screen  Shows:  0  K  -  0 

MY  YYYFIFTH  LINE 

Separate  the  two  lines  by  inserting  an  end-of-line  character. 
Ybu  Type:  >6  i  /  /  [  enter  | 

Screen  Shows:  >6  i/  / 

MY  YYY 
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Note:  The  end  of  line  charact^  is  inserted  before  the  current 
position  of  the  edit  pointer. 

You  Type:  L  |ENT1R| 

Screen  Shows:  L 

FIFTH  LINE 


Sample  Session  2 

Clear  the  buffer  by  deleting  its  contents. 
You  Type: 


CTRL   7    D*  ENTER 


Insert  lines. 
"Sou  Type: 


□ONE  TWO  THREE  1  .8  |  HfTER  I 
□ONE  flNTERl 


□DCTHREE  I  ENTER  | 


ODNE  TWO  THREE  2.01  ENTER  1 


ODNE  I  ENTER  | 
□DTWD  rWERl 
DttlTWREE  [enterI 


Screen  Shows: 


□  DME  TWO  THREE  3  .  0  |  ENTER  | 
ONE  TWD  THREE  1.0 
ONE 
TWO 
THREE 
ONE  TWD  THREE  2.0 
ONE 
TWD 
THREE 
□NE  TWO  THREE  3.0 

Go  to  the  top  of  the  text,  and  display  all  lines  in  the  buffer. 


You  Type: 
Screen  Shows: 


rcmllTI  L«  I  ENTER  I 
"L» 

ONE  TWD  THREE  1  . 0 
DHE 
TWO 

THREE 
ONE  TWO  THREE  2.0 
ONE 
TWO 

THREE 
ONE  TWD  THREE  3.0 
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Search  for  the  next  occurrence  of  TWO. 
Ifeal^e:  s  "TWO"  CenterI 

Screen  Shows:  s-twq" 

□  HE  TWO  THREE   1  .  0 

Search  for  all  occurrences  of  TWO  that  are  between  the  edit 
pointer  and  the  end  of  the  buffer. 

You  Type:  s  *  / two  /  |  enter  | 

Sisre^  libows:         s  « /  TW  □  / 

□NE  TWO  THREE  1 .0 

TWO 

ONE  TWO  THREE  2.0 
TWO 

□HE  TWO  TWREE  3.0 

Go  to  the  top  of  the  btrffer,  and  change  the  first  occurraae©  ef 
THREE  to  ONE. 

You  Type:  rctRlKTl  C/THREE/ONE/  |  ENTER  | 

Screen  Shows:  *  c/three/dne/ 

ONE  TWO  ONE   1  .  0 

Move  the  edit  pojnter  to  the  top  of  the  buffer.  Set  the  anchor  to 
Column  2,  and  then  use  the  search  command  to  find  each  occur- 
rence of  TWO  that  begins  in  Column  2.  Skip  all  other 
occurrences. 

You  Type:  fcTBlHTl  ft2  s«/TMD/ [EirrER  l 

Screen  Shows:  "  A 2  s*/TWO/ 

TWO 

TWO 

Move  the  edit  pointer  to  the  top  of  the  buffer.  Set  the  anchor  to 
Column  1,  and  change  each  occurrence  of  ONE  that  begins  in 
that  column  to  XXX. 

Note;  ONE  in  Line  1  is  not  changed,  since  it  does  not  begin 
in  Column  1. 

You  Type:  rcTRiKTI  flC*/ONE/xxx/  |enter| 

Screen  &3iows:  "  ac»/qne/xxx/ 

XXX  TWO  ONE   1  .  0 

XXX  TWO  THREE  2.0 
XXX 

XXX  TWO  THREE  3.0 
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Go  to  the  top  of  the  buffer,  and  display  the  text. 
IBm  Type:  rBmHTlL*  | enter | 

Screen  Shows:  L  * 

XXX  TWO  ONE   1  .  0 
XXX 
TWO 
THREE 
XXX  TWO  THREE  2.0 
XXX 
TWO 
THREE 
tit  TWO  THtEE  3.0 

Chmm  *e  moaining  ONE  to  XXX. 

Note:  The  anchor  is  no  longer  set.  It  is  reset  to  zero  after 
each  command  is  executed. 

You  Type:  C/DNE/XXX/  |enter| 

Screen  Shows:  c/DN E  /  x  x  x  / 

XXX  TWO  XXX  1.0 

Move  to  the  beginning  of  the  current  line. 
You  Type:  -  0  |  enter  | 

Screen  Shows:  -  a 

XXX  TNO   XXX  1.0 

Change  three  occurrences  of  XXX  to  ZZZ.   

'^'I^^fi^  ca/xxx/zzz/  \mm] 

Screen  Shows:         C3/ x x x /zzz/ 

ZZZ  TWO  XXX  1.0 
zzz  TWO  ZZZ  1.0 
ZZZ 

Sample  Sessicm  S 

Qmbp  the  boflfef     Wrtj»f  its  etrnteaits:  

You  Type:  fCTRLlfT]  D«  |  enter  | 
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Display  the  directory  of  buffers  and  macros.  The  dollar  sign  ($) 
identifies  the  secondary  buffer  as  Buffer  0.  The  asteri^  (*)  iden- 
tifies the  primary  buffer  as  Buffer  1.  Edit  has  no  macros  defined. 
This  is  the  initial  environment  when  you  start  Edit. 

You  Type:  ,  Dl  R  I  ENTER  I 

Screen  Shows:  .  D I R 

BUFFERS: 
$  0 
•  1 

MACROS s 

Insert  some  lines  into  Buffer  1  so  that  later  you  can  identify  it. 
You  Type:  DBUFFER  ONE  1  .  0  |  enter  | 

□BUFFER  ONE  2  .  0  |  ENTER  | 
□BUFFER  ONE  3.0  |  ENTER  | 
DBUFFER  ONE  4  .  0  |  ENTER  | 

Screen  Shows:  BUFFER  one  i  .  0 

BUFFER  ONE  2.0 
BUFFER  ONE  3.0 
BUFFER  ONE  4.0 

Display  the  text  in  Buffer  1. 

You  Type:  rcTRLllTI  L*  \  enter  | 

Screen  Shows:  *L» 

BUFFER  ONE  1  .  0 
BUFFER  ONE  2.0 
BUFFER  ONE  3.0 
BUFFER   ONE  4.0 

Make  Buffer  0  the  primary  buffer.  Buffer  1  becomes  the  second- 
ary buffer. 

You  Type:  B0  |  enter  I 

Screen  Shows:  B0 

Display  the  directory  of  buffers  and  macros. 

Note:  The  symbols  identifying  the  buffers  are  now  reversed. 
You  Type:  .  D I R  |  ENTER  I 

Screen  Shows:  .  D I R 

BUFFERS: 
$  1 
♦  0 

MACROS : 
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Insert  some  lines  into  Buffer  0. 


You  Type: 


Screen  Shows: 


DBUFFER  mm  1  .0  I  ENTER  | 
DBUFFER  ZEiD  2  .  0  |  ENTER  | 
OBUFFER  ZERO  3  .  0  |  ENTER  | 
DBUFFER  ZERO   4  .  0  |  ENTER  | 
BUFFER  ZERO  1.0 
BWFER  lERO  2.B 
BUFFER  ZERO  3.0 
BUFFER  ZERO  4.0 


Display  the  text  in  Buffer  0. 
You  Type: 
Screen  Shows: 


(CTRLim  L»  I  ENTER  J 


SUFFER  ZERO  1 . 

BUFFER  ZERO  2. 
BUFFER  ZERO  3. 
BUFFER  ZERO  4. 


Switch  to  Buffer  1. 
You  Type; 
Screen  Shows: 

Display  the  text  In  Buffer  1. 
You  Type: 
Screen  Shows: 


B  1  ENTER  I 


CTrTIITI  L»  I  ENTER  I 


BUFFER 
BUFFER 
BUFFER 
BUFFER 


ONE  1. 
ONE  2. 
ONE  3, 
ONE  4. 


Move  the  edit  pointra:  to  Line  3  in  this  buffer. 
You  Type:  +  2  I  enter  | 

Screen  Shows:  +2 

BUFFER  ONE  3. 


Switch  to  Buffer  0. 
You  Type: 


B0  I  ENTER  I 
B0 


Display  the  text  in  Buffer  0. 
You  Type: 
Screen  Shows: 


L*  I  ENTER  I 
L* 

BUFFER  ZERO  1  . 

BUFFER  ZERO  2. 

BUFFER  ZERO  3, 

BUFFER  ZERO  4. 
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Move  the  edit  pointer  to  Ldne  2  in  this  buffer. 
You  Type:  +  |  enter  | 


Screen  Shows: 


BUFFER  ZERO  2.0 


Switch  to  Buffer  1. 

You  Type:  1  j  mm] 

Screen  Shows:  B 

Display  the  text  in  Buffer  1  from  the  current  position  of  the  edit 
pointer. 

Note:  The  position  of  the  edit  pointer  has  not  changed  since 
you  switched  to  Buffer  0. 

You  Type:  L  *  |  enter  | 

Screen  Shows:  L  * 

BUFFER  ONE  3.0 
BUFFER   ONE  4.0 

Switch  to  Buffer  0.   

You  Type:  B0  |  enter  | 

Screen  Shows:  B0 

Display  the  text  in  Buffer  0  from  the  current  position  of  the  edit 
pointer. 

Note:  The  poisltlon  of  the  edit  pointer  has  not  changed  since 
you  switched  to  Bufjter  1. 

You  Type:  L  *  1  enter  | 

Screen  Shows:  L  * 

BUFFER  ZERO  2,0 
BUFFER  ZERO  3,0 
BUFFER  ZERO  4.0 

Delete  the  contents  of  Buffer  0. 

You  Type:  j  ctrl  |[T|  d*  [  enter  | 

Screen  Shows:  "  D  » 

BUFFER  ZERQ  1 . 0 
BUFFER  ZERD  2.0 
BUFFER  ZERO  3.0 
BUFFER  21 R0  4,-0 

Make  Buffer  1  the  primary  buffer  and  Buffer  0  the  secondary 

buffer. 

You  Type:  B  |  ENTER  I 

Screen  Shows:  B 
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Move  two  lines  from  the  primary  buffer  (Buffer  1)  into  the  sec- 
ondary buffer  (Buffer  0). 

You  Type:  rCTRLlfTI  P2  |  ENTER  I 

Screen  Shows:  *P2 

BUFFEt  ONE  1.0 
BUFFER  DNE  2.0 

Switch  to  Buffer  0,  and  show  that  the  lines  were  moved  to  it. 
You  Type:  B0|  ctrl  |[TlL  *  I  enter  | 

Screen  Shows:  B  0  "  L » 

BUFFER  ONE  1.0 
BUFFER  DNE  2.0 

Swilch  to  Buffer  1.  Oo  to  the  bottom  of  the  buff^,  aai  fit  the 
text  out  of  the  secondary  buffer. 

You  Type:  B/G*  |  enter] 

Screen  Shows:  b/g* 

BUFFER  DNE  1.0 
BUFFER  DNE  2.0 

Show  the  contents  of  the  bxiffer. 

Note:  Hie  order  of  the  lines  is  changed  as  a  result  of  mov- 
ing the  text. 

%u  Type:  1  ctrl  HT|l*  [  enter  | 

Screen  Shows:  *  L  ♦ 

BUFFER  DNE  3.0 

BUFFER  ONE  4.0 

BUFFER  ONE  1.0 

BUFFER  ONE  2.0 

Move  two  lines  into  the  secondary  buffer. 
"Sou  Type:  P  t  1  enter  | 

Scre^  Shows:         p  e 

BUFFER  DNE  3.0 
BUFFER  DNE  4.0 

Move  to  the  bottom  of  the  buffe,  and  get  the  lines  back  out  of 
the  secondary  buffer. 

Yau  Tyipe:  /G»  |  enter  | 

Screen  Shows:  /#• 

BUFFER  DNE  3.0 
BUFFER  DNE  4.0 
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Show  that  the  order  of  the  lines  is  restored. 
You  Type:  fCTRLHTlL  » 

Screen  Shows:  L  ♦ 

BUFFER  ONE  1 . 0 
BUFFER  ONE  2.0 
BUFFER  ONE  3.0 
BUFFER  ONE  4.0 


Sample  Session  4 

Clear  the  buffer  by  deleting  its  contents: 

You  Type:  fCTRniTiD*  I  ENTER  I 


Enter  some  lines  of  text. 
Ybu  Type; 


□LINE   DNE  I  ENTER  I 


□  SECOND  LINE   OF  TEXT  I  ENTER] 


□THIRD  LINE  DF  TEXT  [ENTER| 
nrOURTM  LINE  rWfERl 


□FIFTH  L  INE  I  ENTER  I 


Screen  Shows: 


□LAST  LINE  I  ENTER  | 
LINE  ONE 
SECOND  LINE  DF  TEXT 
THIRD  LINE  OF  TEXT 
FOURTH  LINE 
FIFTH  LINE 
LAST  LINE 

Open  the  file  Oldfile  for  writing. 

You  Type:  .WRITE"oldf  ile"  |  ENTER  | 

Screen  Shows:  .WRlTE"oldf  ile" 

Write  all  lines  to  the  file. 
You  Type: 
Screen  Shows: 


fliniTlM*  I  ENTER  J 
"N* 

LINE  DNE 

SECOND  LINE  OF  TEXT 
THIRD  LINE  OF  TEXT 

FOURTH  LINE 
FIFTH  LINE 
LAST  LINE 

*END  OF  TEXT* 


Close  the  file. 
You  Type: 
Screen  #hows: 


.WRITE//  I  ENTER  | 
.WRITE// 
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Yerify  that  the  buffer  is  empty. 

■You  Type:  |  ctrl  |fT|L*  |  enter  | 

Screen  Show^:  "L* 

Open  the  file  Oldfile  for  reading. 

You  Type:  .  REftP-'oldf  i le"  |enter| 

Screen  Shows:  .  RE AD"o  1  df  1 1  e" 

Create  a  new  file  called  New^le  fia*  writing. 

You  Type:  .  NR lTE"newf  i  le"  (InterI 

Screen  Shows:  .  NR  I  TE"newf  i  le" 

Read  four  lines  from  the  input  file.  The  screen  shows  the  lines  as 
they  are  read  in. 

You  Type:  R4  I  enter  | 

Screen  Shows:  R  4 

LINE  ONE 

SECOND  LINE  OF  TEXT 
THIRD  LINE  OF  TEXT 
FOURTH  LINE 

Read  all  the  remainilif  tet  from  the  file.  The  screen  shows  the 
lines,  ^en  there  Is  no  mm  test,  the  screen  shows  &e  •EN©  Of 
FILE*  message. 

You  Type:  R  •  |  enter  | 

Screen  Shows:  R  * 

FIFTH  LINE 
LAST  LINE 

•END  or  FILE* 

€k>  to  the  top  of  the  buffer,  and  display  the  text  to  make  siure  it 
is  inserted  into  the  bufifer. 

You  Type:  rcTRnfTlL*  I  enter  | 

ScreCT  Shows:  "L* 

LINE  ONE 

SECOND  LINE  OF  TEXT 
THIRD  LINE  OF  TEXT 
FOURTH  LINE 
FIFTH  LINE 
LAST  LINE 
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Write  three  lines  to  the  output  file,  and  display  the  lines. 
You  Type;  W3  |  enter  | 

Screen  Shows:  ui3 

LINE  ONE 

SECOND  LINE   OF  TEXT 
THIRD  LINE  QF  TEXT 

Move  to  the  nest  line  and  display  it. 
■^att  Types  +  |  enter  | 

Screen  SIiows:  + 

FIFTH  LINE 

Show  that  when  writing  lines,  the  editor  starts  at  the  current 
line  and  not  at  the  top  of  the  buffer. 

You  Type:  M  |  enter  | 

Screen  Shows:  M 

FIFTH  LINE 

Go  to  the  top  of  the  buffer,  and  display  the  text  to  be  sure  that 
the  lines  were  written  to  the  output  file. 

You  Type:  (IfirirfiL*  \  wm] 

Scre^  Shows:  "  L  * 

FOURTH  LINE 
LAST  LINE 

Clear  the  buffer. 

Yju  Type:  |ctrl|(T1d»  | enter! 

Screen  Shows:  "D* 

FOURTH  LINE 
LAST  LINE 

Switch  to  Buffer  2.  Open  the  input  file  Oldfile,  and  read  two 
lines  from  it. 

You  Type:  B2   ,REAP"oldf  ile"  R2  I  ENTER  I 

Screen  Shows:         B2  .R^EfiD"oldf  lie"  R2 

LINE  ONE 

SECOND  LINE  OF  TEXT 

Switch  to  Buffer  1.  Open  the  input  file  Oldfile  and  read  one  line 
of  text. 

You  Type:  B  .lilEAD"oldf  lie"  R  flNTERl 

Screen  Shows:  B  .RIAD"oldf  I  le"  R 

LINE  ONE 
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Switch  to  Buffer  2,  and  read  one  line. 

Note:  Your  place  in  the  file  was  not  lost. 
Tfou  Type:  B2  R  |  enter  | 

Screen  Shows:         B2  r 

THIRD  LINE   OF  TEXT 

Switch  to  Buffer  1,  and  read  one  line  of  text. 

Note:  Your  place  in  the  file  was  not  lost. 
You  Type:  B  R  |  ENTER  | 

Screen  Shows:  B  R 

SECOND  LINE  OF  TEXT 

Switeh  to  Bttffei'  %  mA  delete  its  cefitealt,  

You  Type:  B2  [ctrOITJD*  |  ENTER! 

Screen  Shows:  B2  "D* 

LINE  ONE 

SECOND  LINE  OF  TEXT 

rmm  itm  or  tixt 

Insert  some  ^ra  lines  into  the  buffer. 

YouType:  dextra  line  one  | enter | 


□  EXTRA  LINE  TWO  |  ENTER ] 

Screen  Shows:  EXTRA  LINE  ONE 

EXTRA  LINE  TWO 

Try  to  write  B2  buffer  to  file.  It  fails  because  you  have  not 
opened  a  file  in  this  buffer. 

You  Type:  [CTRr|(T|W»  |  ENTER  I 

Screen  Shows:  "W* 

•FILE  CLOSED* 

Close  the  file  for  Buffer  1,  and  return  to  Buffer  2. 
YouType:  B  .write//  B2  [enter I 

Screen  Shows:  B  .WRITE//  B2 

Open  the  old  "write"  file  for  reading,  and  then  read  it  back  in. 
YouType:  .  RE  AD"newf  i  l  e"  R  *  |  ENTER  | 

Screen  Shows:  .READ"newf  iie"  R* 

LI«E  OWE 

SECOND  LINE  OF  TEXT 
THIRD  LINE  OF  TEXT 
FIFTH  LINE 

•END  OF  FILE* 
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Display  the  contents  of  the  buffrar. 

Note:  It  read  the  file  into  the  beginning  of  the  buffer,  since 
that  was  the  position  of  the  edit  pointer. 

You  Type:  [CTRTirTlL*  I  ENTER  I 

Screen  Shows:  *L» 

LINE  ONE 

SECOND  LINE  OF  TEXT 
THIRD  LINE  OF  TEXT 
FIFTH  LINE 
EXTRA  LINE  ONE 
EXTRA  LINE  TWO 


Sample  Session  5 

Delete  all  text  from  the  edit  buffer. 
YovL  Type: 


CTRL|[7lD*  I  ENTER  | 


Insert  three  lines. 
You  Type: 


Screen  Shows: 


□LINE  ONE  [EWTERI 

DLINE  TWO  (  ENTER  | 
DLINE  THREE  |  ENTER  | 
LINE  ONE 
LINE  TWO 
LINE  THREE 

Qreate  a  new  macro  using  an  empty  string. 
You  Type:  .  MAC /  /  |  ENTER  I 

Screen  Shows:  M : 

Display  the  contents  of  the  macro  mode,  which  is  now  open. 

Note:  The  E  prompt  is  now  M 
You  Type: 
Screen  Shows: 


FilLlfTlL*  I  ENTER  I 
L» 


Define  the  macro. 
Yovi  Type: 

Screen  Shows: 


DFIND  1  ENTER  I 


nS"TWD"  I  ENTER  | 

FIND 

S"TWO" 


Display  the  contents  of  the  macro. 

You  Type:   

SlflP^^ti  Shows:  *L» 


CTRLJITJL*  LENTERl 


FIND 
S"TWD" 
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Close  the  macro's  definition. 

You  Type:  Q  |  enter  | 

Screen  Shows:  E : 

Display  the  directory  of  buffers  and  macros. 
You  Types.  .dir  j enter | 

BUFFERS: 
$  0 
*  1 

MACROS! 

FIND 

Display  the  contents  of  the  edit  buffer. 

IbuType;  [cTRp[y]L»  [enter] 

Screen  Shows:         "  l  * 

LINE  DNE 
LINE  TWQ 
LINE  THREE 

Use  the  FIND  macro  to  find  the  string  TWO. 
You  Type:  .FIND  |  enter  | 

Screcai  Shows:  .find 

LINE  TWO 

Reopen  the  definition  of  the  FIND  macro. 

You  Type:  .  MAC/ F I HS/  UnterI 

Screen  Shows:  .MAC/ FIND/ 

M: 

Show  that  the  macro  is  still  intact. 

You  Type:  rcTRLllTlL*  I  enter  I 

Screen  Shows:  "L* 

Fito 

S"TWD" 

Add  the  numeric  parameter  and  the  string  parameter  to  the 
macro's  header. 

You  Type:  C/FIND/FIND  #N   $5TR/  I  ENTER  I 

Screen  Shows:  c/find/find  ifN  $str/ 

FIND  #H  $STR 

Mow  to  the  second  line  of  the  macro. 
You  Type:  +  |  enter] 

Screen  Shows:  + 

S"TWD" 
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Give  the  macro's  parameters  to  the  S  command.  Now  the  FIND 
macro  will  perform  the  same  function  as  the  S  command. 

You  Type:  C/"TWD"/   #N   $5TR/  [ENTER  I 

Screen  Shows:  c/"TWO"/  #N  $STR 

S  #N  $STR 

Close  the  macro's  definltioti. 

You  Type:  Q  I  enterJ 

Screen  Shows:  E : 

Display  the  contents  of  the  edit  buffer. 

You  Type:  rcTREKTlL*  |, ENTER  I, 

Screen  Shows:  "L* 

LINE  ONE 

LINE  TND 
LINE  THREE 

Use  the  FIND  macro  to  find  the  next  two  occurrences  of  LINE. 
You  Type:  .find  2  /line/  flffEgl 

Screen  Shows:  .FIND  2  /line/ 

LINE  ONE 

line  two 


Create  a  new  macro. 
You  Type: 
Screen  Shows: 


.MAC// 
.««C// 
M: 


ENTER 


Define  the  macro  FIND_LINE,  which  performs  the  same  func- 
tion as  the  S  command  except  that  it  returns  the  edit  pointer  to 
the  head  of  the  line  after  finding  the  last  occurrence  of  STR. 
You  Type:  DFIND-LINE  #N   $STR  |  ENTER  | 

Screen  Shows:         find_liN  E  #  n  $str 


YovL  Type: 
Screen  Shows: 

Turn  off  the  verify  mode. 
You  Type: 
Screen  Shows: 


OS  #K  tST«  [BiTERl 
S  #N  iSTt 


OV0 
V0 


ENTER 


Move  the  edit  pointer  to  the  first  character  of  the  current  line. 
You  Type:  -  0  |  enter  ] 

Screen  Shows:  -  0 
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Close  the  macro's  definition. 

You  Type:  Q  |  enter  | 

Screen  Shows:  Q 


Display  the  contents  of  the  edit  buffer. 

You  Type;  rcTRLllTiL*  | enter! 

ScFeen  Shows:  *L» 

line:  one 

LINE  TWO 
LINE  THREE 

Use  the  FIND_XINE  macro  to  search  for  the  string  TWO. 
You  Type:  ,  F  I  ND^L  I  N_E  / two /  fENTERl 

Screen  'Ihowss:         .  F I  MD-.L,i  NEv  rm/ 

LINE  TWO 

Show  that  the  FIND_XINE  macro  left  the  edit  pointer  at  Urn 
head  of  the  line. 

You  Type:  L  I  enter  1 

Screen  Shows:  L 

LINE  im 

Create  a  new  macro. 


You  Type:  .MAC//  |  ENTER  | 

Screen  Shows:  .MAC// 
M: 
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Use  the  exclamation  point  (!)  command  to  comment  itself.  Tjrpe 

the  following: 

□  CDNVERT_TD_LINES  #N  |  ENTER  | 

□  !  This  is  a  comment  |  ENTER  | 
0  !  I  ENTER  I 

D  !  This  macro  converts  the  next  n  | ENTER  | 
D  !  space  characters  to  new  line  |  ENTER | 
D  !  characters.  | ENTER  | 


□  V0  !  Turn  verify  mode  of  f  |  ENTER  | 

n  !  to  prevent  litertedlatfe  ^isults  |  ENTER  | 

D  !  from  being  displayed.  |  ENTER  I 

D  ! I  ENTER  I   

□  [  !  le  glti  l  osp  |  6NTER  | 

□  .SEARCH/  /  !  Search  for  the  space  character.  |  ENTER | 

D  I//  !  Insert  empty  line  (new  line  character).  |  ENTER  | 

□  -  !  Back  up  one  line.  |  ENTER | 

□  C/  //  !  Delete  the  next  space  character.  [  ENTER | 

□  L  +  !  Show  line,  move  past        t ENTER  | 

□  1  *N  !  End  of  loop.  Repeat  *N  times.  |  ENTER | 

Close  the  macro's  definition. 

You  Type:  Q  I  enter  I 

Screen  Shows;  Q 

E  : 

Display  the  contents  of  the  edit  buffer. 

Ijtt  Typei  fCTRLlfTlL*  |  enter  | 


Screm  Shows:  "L* 

LINE  ONE 
LINE  TWO 

LINE  THREE 

Convert  all  space  characters  to  new  line  characters. 

Note:  The  loop  stops  when  the  C  command  in  the  macro 
cannot  fted  a  space  to  delete. 

You  Type:  .  CDNVERT_TD_L  I  NES  »  I  ENTER  I 

Screen  Shows:  .  cdnvert_td_l  I  NES  » 

LINE 

LINE 

LINE 
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Display  the  contents  of  the  edit  buffer. 

"Sou  Type:  fcTRrifTlL*  |  enter  | 

Scre0n  Shows:  "L* 

LINE 

ON'E 

LINE 

TWO 

L  INE 

THREE 


7-54 


Macro  Text  Editor  I  7 


Edit  Quick  Referemit  iiuttnwy 


EDIT 


EDIT  newGle 


EDIT  dldme 


EDIT  oMfife 
mewffle 


OS-9  loads  the  editor  and  starts  it  without 
creating  any  read  or  write  files.  Perform  text- 
file  operations  by  opening  files  after  the  editor 
is  running. 

OS-9  loads  the  editor  and  starts  it.  If  mwfile 
does  not  exist,  Edit  creates  it  and  makes  it  the 
initial  write  file.  Although  this  command  does 
not  create  an  initial  read  file,  you  can  open 
read  files  after  starting  Edit. 

OS-9  loads  the  editor  and  starts  it,  making 
the  initial  read  file  oldfik.  The  editor  creates 
a  new  file  called  SCRATCH  as  the  initial 
write  file.  When  the  edit  session  is  complete, 
Edit  deletes  oMfile  and  renames  SCRATCH  to 
oldfth. 

OS-9  loads  the  editor  and  starts  it.  The  initial 

read  file  is  oldfik.  The  editor  creates  a  file 
called  newfik  as  the  initial  write  file. 


Edit  Commands 

.MACRO  Executes  the  macro  specified  by  the  name  fol- 

lowing the  period  (.). 

!  Places  comments  inside  a  macro,  and  ignores 

the  remainder  of  the  command  line, 

0  Inserts  a  line  before  the  current  position  of  the 
edit  pointer. 

1  ENTER  I  Moves  the  edit  pointer  to  the  next  line,  and 

displays  it. 

+  n  Moves  the  edit  pointer  forward  n  lines  and  dis- 

plays the  line. 

•n  Moves  the  edit  pointer  backward  n  lines  and 

displays  the  line. 

H-O  Moves  the  edit  pointer  to  the  last  character  of 

the  line. 
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-0  Moves  the  edit  pointer  to  the  first  character  of 

the  current  line  and  display's  it. 

>B  Moves  the  eilt  pimter  forward  n  characters, 

<n  JVbves  the  ^t  pointer  backward  n  characters. 

I  CTRL  lin  or  □  for  Moves  the  edit  pointer  to  the  beginning  of  the 

external  ti^. 

terminals 

/  Moves  the  edit  pointer  to  the  end  of  the  text. 

[commands]  n    Repeats  the  sequence  of  commands  between 
the  two  brackets  n  times, 

:  Skips  to  the  end  of  the  innermost  loop  or 

macro  if  the  fail  flag  is  not  on. 

An  Sets  the  SEARCH/CHANGE  anchor  to  Col- 

umn n,  fegtrictfng  searches  and  changes  to 

those  strings  starting  in  Column  n.  This  com- 
mand remains  in  effect  for  the  current  com- 
mand line. 

AO  Returns  the  anchor  to  the  normal  mode  of 

searching  so  that  strings  are  found  regardless 
of  the  column  in  which  they  start. 

Bfl  Makes  buffer  n  the  primary  buffer. 

Cn        Slr2       Changes  the  next  n  occurrences  of  strl  to  str2. 

Dn  Deletes  n  lines. 

En  sir  Extends  (adds  the  string  to  the  end  of)  the 

mmt  n  lines. 

Gb  Gets  n  lines  from  the  secondary  buffer,  start- 

ing from  the  top.  Inserts  the  lines  before  the 
current  position  in  the  primary  buffer. 

In  str  Inserts  a  line  containing  n  copies  of  the  string 

before  the  current  position  of  the  edit  pointer. 

Kn  Kills  n  characters  starting  at  the  current 

position  of  the  edit  pointer. 

Ln  Lists  (displays)  the  next  n  lines,  glwtfng  at 

the  current  position  of  the  edit  pointer. 
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Mn  Changes  workspace  (memory)  size  to  n  bytes. 

Pji  Puts  (moves)  n  lines  from  the  position  of  the 

edit  pdMer  m.  the  ^Smsry  to  the  fogi- 
tion  of  the  edit  poiater  in  the  smsmSmy  h^ibr. 

Q  Quits  editing  (and  temainates  editor).  If  you 

specified  a  file(s)  when  you  entered  Edit, 
Buffer  1  is  written  to  the  output  file.  The 
remainder  of  the  input  file  ig,  copied  to  the  out- 
put ffle.  AU  ffibs  are  elssei. 

Rjn  R^vils  n  lines  from  the  bu£^s  input  file. 

Sn  5^  Searches  for  the  next  n  occurrences  of  the 

string. 

Til  Tabs  to  Column  n  of  the  present  line.  If  n  is 

greater  than  the  line  length,  Edit  extends  the 
line  with  space. 

U  Unextends  (truncates)  a  line  at  the  current 

position  of  the  edit  pointer. 

Vmode  Turns  the  verify  mode  on  or  off. 

Wii  Writes  n  lines  to  the  buffer's  output  file. 

Xn  Displays  n  lines  that  precede  the  edit  position. 

The  current  line  is  counted  as  the  first  line. 

Pseudo  Macros 

.CHANGE  n       Changes  n  occurrences  of  strl  to  str2. 

JML  sir  Deletes  the  xsmto  ^ed&d  1^ 

j)IR  Displays  the  d^ectory    hufflers  stnd  macatss. 

.EOB  l^^ts  isrihsmd  <ai  the  btAr. 

.EOF  Tests  fer  the  aad  of  the  file. 

.EOL  Tests  for  the  end  of  the  line. 

.F  Exits  the  innermost  loop  or  macro  and  sets  the 


.LOAD  sir         Loads  macros  from  the  path  specified  in  the 

string. 
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MAC  str 

.NEOB 
.NEOF 
,NEOL 
.NEW 


.NSTB  str 


.READ  str 
.S 

.SEARCH  n 
sly 

.SAVE  strl 
str2 

.SHELL 
command  line 

.SIZE 

.STAR  n 
.STR  str 

.WRITE  str 

.ZERO  n 
[ 


Opens  the  macro  specified  by  the  string  for 
definition.  If  ytm  give  an  empty  string,  Edit 

creates  a  new  macro. 

Tests  for  not  end  of  buffer. 
Tests  for  not  end  of  file. 
Tests  for  not  end  of  line. 

Writes  all  lines  up  to  the  current  line  to  the 
initial  output  file,  and  then  attempts  to  read 
an  equal  amount  of  text  from  the  initial  input 
file.  The  text  read-in  is  appended  to  the  end  of 
the  edit  buffer. 

Tests  to  see  if  string  does  not  match  the  char- 
acters at  the  current  position  of  the  edit 
pointer. 

Opens  an  OS-9  text  file  for  reading,  using 
j^Wg  as  the  pathlist. 

Exits  the  innermost  loop  or  macro  and  suc- 
ceeds (clears  the  fail  flag). 

Searches  for  n  occurrences  of  str. 


Saves  the  macros  specified  fai  $trj  on  the  file 
specified  by  the  pathlist  in  str§. 

Calls  OS-9  shell  to  execute  the  command  line. 


Displays  the  size  of  memory  used  and  the 
amount  of  naemory  available  in  the  ■WDrkspaee, 

Tfests  to  see  if  n  equals  asterisk  (infinity). 

Tests  to  see  if  string  matches  the  characters  at 
the  current  position  of  the  edit  pointer. 

Opens  an  OS-9  text  for  writing,  using  str  as  a 
pathlist. 

Tests  n  to  see  if  it  is  zero. 

Starts  at  a  macro  loop;  press  I  CTFtL  lfTl. 

Ends  at  a  macro  loop;  press  I  ctrl  iID. 
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Moves  edit  pointer  to  beginning  of  buffer; 
press  I  CTRL  IfTI. 


Editor  Error  Messages 


BAD  MACRO 
NAME 

BAD 

NUMBER 

BAD  VAR 
NAME 

BRACKET 
MISMATCH 

BREAK 


DUPL 
MACRO 

END  OF 
FILE 

*FILE 
CLOSED* 


MACRO  IS 
OPEN 

MISSING 
DELIM 

NOTFOOTD 


You  did  not  begin  the  first  line  in  a  macro 
with  a  legal  name.  You  can  close  the  definition 
of  a  macro  after  you  give  it  a  legal  name. 

You  have  entered  an  illegal  numeric  parame- 
ter, probably  a  number  greater  than  65,535. 

You  have  specified  an  illegal  variable  name, 
omitted  the  variable  name,  or  included  a  $  or 
#  character  in  the  commands  parameter  list. 

You  have  not  entered  brackets  in  pairs  or  the 
brackets  are  nested  too  deeply. 

You  pressed  I  ctrl  Ifcl  or  E  to  interrupt  the  edi- 
tor. Aftesr  printing  the  en-or  message,  the  edi- 
tor returns  to  command  entry  mode. 

You  attempted  to  close  a  macro  definition  with 
an  existing  macro  name.  Rename  the  macro 
before  trying  to  close  its  definition. 

You  are  at  the  end  of  the  edit  buffer. 


You  tried  to  write  to  a  file  that  is  not  open. 
Either  specify  a  write  file  when  starting  the 
editor  from  OS- 9,  or  open  an  output  file  usii^ 
the  .WRITE  pseudo  macro. 

You  must  close  the  macro  definition  before 
using  the  command. 

The  editor  could  not  find  a  matching  delimiter 
to  complete  the  string  you  specified.  You  must 
put  the  entire  string  on  one  line. 

The  editor  cannot  find  the  specified  string  or 
macro. 
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UNDEFINED 
VAR 


WHAT  ?? 


WORKSPACE 
FULL 


used  a  variable  that  is  not  specified  in  the 
macro's  definition  parameter  list.  A  vaiiaMe 
parameter  can  be  used  only  in  the  macro  in 
which  it  is  declared. 

The  editor  does  not  recognize  a  command.  You 
typed  a  command  that  does  not  exist  or  mis- 
spelled a  name. 

The  buffer  did  not  have  room  for  the  text  you 
want  to  insert.  Increase  the  workspace,  or 
remove  some  tegt. 
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OS-9  Error  Codes 


The  following  table  shows  OS-9  error  codes  in  hexadecimal  and 
decimal.  Error  codes  other  than  those  listed  are  generated  by 
programming  languages  or  user  programs. 


OS-9  Error  Codes 


Code 

HEX   DEC       Code  Mi»»itii 


$01      001  UNCONDITIONAL  ABORT.  An  error  occurred 

jfrom  which  OS-9  cannot  recover.  All  processes 
are  terminated. 

$02      002  KEYBOARD  ABORT.  You  pressed  UrIAkI  to 

terminate  the  current  operation. 

$03  003  KEYBOARD  INTERRUPT.  You  pressed 
I  SHIFT  II  break]  either  to  cause  the  current  opera- 
tion to  function  as  a  background  task  with  no 
video  display  or  to  cause  the  current  task  to 
terminate. 

$B7  183  ILLEGAL  WINDOW  TYPE.  You  tried  to 
define  a  text  type  window  for  graphics  or  used 
illegal  parameters. 

$B8      184  WINDOW  ALREADY  DEFINED.  You  tried  to 

create  a  window  that  is  already  established. 

$B9  186  FONT  NOT  FOUND.  You  tried  to  use  a  win- 
dow font  that  does  not  exist. 

$BA  186  STACK  OVERFLOW.  Your  process  (or  pro- 
cesses) KefuSres  more  stack  space  than  is 
available  on  the  system. 

$BB      187  ILLEGAL  ARGUMENT.  You  have  used  an 

argument  with  a  command  that  is 
inappropriatev 

$BD     189  ILLEGAL  COORDINATES.  You  have  given 

coordinates  to  a  graphics  command  which  are 
outside  the  screen  boundaries. 
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Code 

HEX    DEC       Code  Meaning 


$BE  190  INTERNAL  INTEGRITY  CHECK.  System 
modules  or  data  are  changed  and  no  longer 
reliable. 

$BF  191  BUFFER  SIZE  IS  TOO  SMALL.  The  data  you 
assigned  to  a  buffer  is  larger  than  the  buffer. 

$C0      192  ILLEGAL  COMMAND.  You  have  issued  a 

command  in  a  form  unacceptable  to  OS-9. 

$C1      193  SCREEN  OR  WINDOW  TABLE  IS  FULL.  You 

do  not  have  enough  room  in  the  system  win- 
dow table  to  keep  track  of  any  more  windows 
or  screetts. 

$C2  194  BAD/UNDEFIIIID  BUFBISR  NtJMBEl.  Ifet 
have  specified  an  illegal  or  luidefined  buffer 

number. 

$C3  195  ILLEGAL  WINDOW  DEFINITION.  You  have 
tried  to  give  a  window  ilkgal  parameters. 

$C4  196  WINDOW  UNDEFINED.  You  have  tried  to 
access  a  window  that  you  have  not  yet  defined. 

$C8  200  PATH  TABLE  FULL.  OS-9  cannot  open  the 
file  because  the  system  path  table  is  full. 

$C9  201  ILLEGAL  VMH  NUMBER.  The  path  number 
is  too  large,  or  you  specified  a  non-existent 

path. 

$CA     202  INTERRUPT  POLLING  TABLE  FULL.  Your 

system  cannot  handle  an  interrupt  request, 
beeause  the  polling  table  does  not  have  room 
ta?  fiiiore  entries. 

$CB  203  ILLEGAL  MODE.  The  specified  device  cannot 
perform  the  mdieftted  input  or  output  function. 

$CC     204  DEVICE  TABLE  FULL.  The  device  table  does 

not  have  enough  room  for  another  device. 
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Code 


$CD  205  ILLEGAL  MODULE  HEADER.  OS-9  cannot 
load  the  specified  module  because  its  sync 
code,  header  parity,  or  cyclic  redundancy  code 
is  incorrect. 

$CE  206  MODULE  DIRECTORY  FULL.  The  module 
directory  does  not  have  enough  room  for 
another  module  entiy. 

$CF  207  MEMOKT  FULL.  Process  address  space  is  ftill 
or  your  computer  does  not  have  sufficient  mran- 
ory  to  perform  the  specified  task. 

$D0  208  ILLEGAL  SERVICE  REQUEST.  The  current 
program  has  issued  a  system  call  contaimng 

an  illegal  code  number. 

$D1      209  MODULE  BUSY.  Another  process  is  already 

using  a  non-shareable  modxde. 

$D2  210  BOUNDARY  ERROR.  OS-9  has  received  a 
memory  allocation  or  deallocation  request  that 
is  not  on  a  page  boundary. 

$D3  211  END  OF  FILE.  A  read  operation  has  encoun- 
tered an  end-of-file  character  and  has 

terminated. 

$D4     212         RETURNING  NON-ALLOCATED  MEMORY. 

The  current  opemisan  has  attempted  to  d^lo- 

cate  memory  not  previously  assigned. 

$D5  213  NON-EXISTING  SEGMENT.  The  file  struc- 
ture of  the  specified  device  is  damaged. 

$D6  214  NO  PERMISSION.  The  attributes  of  the  speci- 
fied, file  or  device  do  not  permit  the  reqviested 

access. 

$D7  215  BAD  PATH  NAME.  The  specified  pathlist  con- 
tains a  syntax  error,  finr  instance  an  illegal 

character. 

$D8  216  PATH  NAME  NOT  FOUND.  The  system  can- 
not find  the  specified  pathlist. 
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Code 


$D9     217         SEGMENT  LIST  FULL.  The  specified  file  is 

too  fragmented  for  further  expansion. 

IDA  218  FILE  ALREADY  EXISTS.  The  specified  file- 
name already  exists  in  the  specified  directory. 

$DB  219  ILLEGAL  BLOCK  ADDRESS.  The  file  struc- 
ture of  the  specified  device  is  damaged. 

$DC  220  PHONE  HANGUP  -  DATA  CARRIER 
DETECT  LOST.  The  data  carrier  detect  is  lost 
on  the  RS-232  port. 

$DD  221  MODULE  NOT  FOUND.  The  system  received 
a  request  to  link  a  module  that  is  not  in  the 
specified  directory. 

$DF     223  SUICIDE  ATTEMPT.  The  current  operation 

has  attempted  to  return  to  the  memory  loca- 
tion of  the  stack. 

$E0  224  ILLEGAL  PROCESS  NUMBER.  The  specified 
process  does  not  exist. 

$E2  226  NO  DHILDRIN.  The  system  has  issued  a 
wait  semfe  request  but  the  current  process 
has  no  dependent  process  to  execute. 

$E3      227  ILLEGAL  SWI  CODE.  The  system  received  a 

software  interrupt  code  that  is  less  than  1  or 
greater  than  3. 

$E4      228  PROCESS  ABORTED.  The  system  received  a 

signal  Code  2  to  terminate  the  current 


$15      229  PROCESS  TABLE  FULL.  A  fork  request  can- 

not execute  because  the  process  table  has  no 
room  for  more  entries. 

$E6      230  ILLEGAL  PARAMETER  AREA.  A  fork  call 

has  passed  incorrect  high  and  low  bounds. 

$E7      231         KNOWN  MODULE.  The  specified  module  is 
for  internal  use  only. 


OS-9  Error  Codm  I A 


Code 

HEX   DEC       Code  lieanixig 


$E8  232  INCORRECT  MODULE  CRC.  The  cyclic 
redundancy  code  for  the  module  being 
accessed  is  bad. 

$E9  233  SIGNAL  ERROR.  The  receiving  process  has  a 
previous,  unprocessed  signal  pending. 

$EA  234  NON-EXISTENT  MODULE.  The  system  can- 
not locate  the  specified  module. 

$EB  235  BAD  NAME.  The  specified  device,  file,  or  mod- 
ule name  is  illegal. 

$EC  236  BAD  MODULE  HEADER,  The  specified  mod- 
ule header  parity  is  incorrect. 

$ED     237  RAM  FULL.  No  free  system  random  access 

memory  is  available:  the  system  address  space 
is  full,  or  there  is  no  physical  memory  avail- 
able when  requested  by  the  operating  system 
in  the  syst^  state. 

$EE  238  UNKNOWN  HIOCESS  ID.  Tim  spe^fted  ^o- 
^ss^  tD  number  is  incorrect. 

$EP  239  NO  TASK  NUMBER  AVAILABLE.  All  avail- 
able task  numbers  are  in  use. 

Umim  Driver  Errors 

I/O  device  drivers  generate  the  following  error  codes.  In  most 
cases,  the  codes  are  hardware-dependent.  Consult  your  device 
manual  fer  more  details. 

Code 

HEX   DEC       Code  Meaning  

$F0     240         UNIT  ERROR.  The  specified  device  unit 

doesn't  exist. 

$F1      241  SECTOR  ERROR.  The  specified  sector  number 

is  out  of  range. 

$P2     242         WRITE  PROTECT.  The  specified  device  is 

write-protected. 
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$F3  243 

$F4  244 

$P5  245 

$F6  246 

$F7  247 

$F8  248 

$F9  24i 

$FA  250 

$FB  251 

$FC  252 

$FD  253 


Code  Meaning  ,4a^ 

CRC  ERROR.  A  cyclic  redundancy  code  error 
occurred  on  a  read  or  write  verify. 

READ  ERROR.  A  data  transfer  error  occurred 
durii^  a  read  operation,  or  i^me  Is  a 
SCF  (tem^radPI  input  buffer  overrun. 

WRITE  ERROR.  An  error  occurred  during  a 

write  operation. 

NOT  READY.  The  device  specified  has  a  not 
ready  status. 

SEEK  ERIOE.  The  system  attempted  a  seek 
operation  on  a  non-existent  sector. 

MEDIA  FULL.  The  specified  media  has  insuf- 
ficient £ree  space  fbr  the  operation. 

WRONG  TYPE.  An  attempt  is  made  to  read  ^ 

incompatible  media  (for  instance  an  attempt  to 
read  double-side  disk  on  single-side  drive). 

DEVICE  BUSY.  A  non-shareable  device  is  in 
use. 

DISK  ID  CHANGE.  You  ehanged  diskettes 

when  one  or  more  files  are  open. 


RECORD  IS  LOCKED-OUT.  Another  pa-ocess 

is  accessing  the  requested  record. 

NON-SHARABLE  FILE  BUSY.  Another  pro- 
cess is  accessing  the  requested  file. 
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Color  Computer  2  Compatibility 


Color  Computer  3  OS-9  Level  Two  provides  compatibility  with 
the  Color  Computer  2  and  OS-9  Level  One  "by  letting  you  use  the 
video  display  in  the  Alphanumeric  mode  (including  Semigraphic 
box  graphics)  and  in  the  Graphics  mode.  To  control  the  display, 
it  has  many  built-in  functions  that  you  activate  using  ASCII 
control  characters.  Any  program  written  in  a  language  using 
standard  output  statements  (such  as  PUT  in  BASIC)  can  use 
these  functions.  Color  Computer  BASIC09  has  a  Graphics  Inter- 
face Module  that  can  automatically  generate  most  of  these  codes 
using  BASIC09  RUN  statements. 

The  Color  Computer's  display  system  uses  a  separate  memory 
area  for  each  Display  mode.  Therefore,  operations  on  the  Alpha 
display  do  not  affect  the  Graphics  display  and  vice-versa.  You  can 

select  either  display  with  software  control.  (See  Getting  Started 
With  Extended  Color  BASIC  for  more  detailed  information.) 

The  system  interprets  8-bit  characters  sent  to  the  display 
according  to  their  numerical  values,  as  shown  in  this  chart: 

Character  Mode/Function 

Range 


(Hex) 


00  -  OE 


Alpha — Cursor  and  screen  control. 
Graphics — Drawing  and  screen  control. 
Alpha,  Graphics — Changing  Palette  colors. 


OF  -  ID 


IB 


Alpha  mode: 

IB  31  2  h  change  cursor  color 

IB  31  c  h  change  foreground  color 

IB  31  d  h  change  background  color 

whme  h  ia  a  hm  number  from  0  to  3F  (0  to 
63  decimal)  which  determines  the  color. 
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Character  Mode/Fimelion 
Range 


Graphies  msM'. 

IB  31  pr  it     changes  foregromwi/ 
background  color 

where  pr  is  a  palette  register  #  (0  -  P, 

hex) 

where  h  is  a  hex  number  from  0  to  3F  (0 
to  63  decimal)  which  determines  the 
color. 


The  device  driver  CC3I0  calls  a  subroutine  module  najjied 
VDGInt  to  handle  all  t^t  and  graphics  f(»  the  Color  Comr 
puter  2  compatibility  mode. 


(Hex) 


20-5F 


80  -  FF 


60  -  7F 


Alpha — Uppercase  charactars. 
Alpha — Lowercase  characters. 
Alpha — Semigraphic  patterns. 
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Alpha  Mode  Display 

The  Alpha  mode  is  the  standard  operational  mode.  Use  it  to  dis- 
play alphanumeric  characters  and  semigraphic  box  graphics.  Use 
it  also  to  simulate  the  operation  of  a  %pical  computer  terminal 
with  functions  for  scrolling,  cursor  positioning,  clearing  the 
screen,  deleting  lines,  and  so  on. 

The  Alpha  mode  assumes  that  each  8-bit  code  the  system  sends 
to  the  display  is  an  ASCII  character.  If  the  high-order  bit  of  the 
code  is  clear,  the  system  displays  the  appropriate  alphanumeric 
chsB-acter.  If  the  high-order  bit  is  set,  OS-9  generates  a  Semi- 
graphic  6  graphics  box.  See  Getting  Started  With  Extended  Color 
BASIC  for  an  explanation  of  semigraphic  functions. 

The  standard  32-column  Alpha  mode  display  is  handled  by  the 
I/O  subroutine  module  VDGInt.  CC3I0  calls  this  module 
(included  in  the  standard  boot  file)  to  process  all  text  and  semi- 
g^^ye  eu^ittt. 

The  fellowinf  chart  provides  codes  for  sra^en  display  and  cursor 

control.  You  can  use  the  functions  from  the  OS-9  system  prompt 
by  typing  DISPLAY,  followed  by  the  appropriate  codes.  For 
instance,  to  clear  the  screen,  type: 

display  0c  |  ENTER  I 

To  position  the  cursor  at  column  16,  Line  5  and  displ£^  the  vrord 
HELLO,  type: 

display  02   30   25  48  45  4c   4c   4f  |  ENTER  | 

%u  can  also  use  the  following  codes  in  a  language,  such  as 
BASIC09.  Tb  do  so,  use  decimal  numbers  with  1^  OBB$  fttnc- 
tion,  such  as: 

print    chr$(02); chr$<48);chr$C37);chr$C72) 
;chr$(e9);chr$(7G);chr$(76);chr$C79) 

Using  Alpha  Mode  Controls  with  Windows 

The  control  functions  in  the  following  chart  also  function  pn^ 
erly  under  the  high  resolution  windowing  systems.  References  to 
"screen"  are  also  references  to  windows. 
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Alpha  Mode  Command  Codes 


Hex  Decimal 
Control  Coniarol 

Code      Code  Name/Function 


$01        01  HOME— Returns  the  cursor  to  the  upper  left 

corner  of  the  screen. 

$02        02  CURSOR  XY— Moves  the  cursor  to  character 

X  of  line  Y.  To  arrive  at  the  values  for  X  and 
Y,  add  20  hexadecimal  to  the  location  where 
you  want  to  place  the  cursor.  ¥m  example,  to 
position  the  cursor  at  Character  5  of  Line  10 
(hexadecimal  A),  do  these  calculations: 

5 

+  20 

=  25  hexadecimal 

OA 
+  20 

=  2A  hasateteml 
The  im»  mm^Sm^  are  $21  aad  $£A. 

$03        03  ERASE  LINE— Erases  all  charactas  on  the 

line  occupied  by  the  cursor. 

$04        04  CLEAR  TO  END  OF  LINE— Erases  all 

characters  from  the  cursor  position  to  the 
end  of  the  line. 
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Hex  Decimal 
Control  Control 

Code  Name/Function 

$05        05  CURSOR  ON-OFF— Allows  alteration  of  the 

cursor  based  on  the  value  of  the  next 
character.  Codes  are  as  follow: 

Defoult 

Hex  Dec    ClmF    Function  Color 


$20 

32 

space 

Cursor  OFF 

$21 

33 

I 

Cursor  ON 

$22 

34 

ii 

Cursor  ON 

$23 

35 

# 

Cursor  ON 

$24 

36 

$ 

Cursor  ON 

$25 

37 

% 

Cursor  ON 

$26 

38 

& 

Cursor  ON 

$2f 

S9 

< 

Cursor  ON 

$28 

40 

( 

Cursor  ON 

$29 

41 

) 

Cursor  ON 

$2A 

42 

* 

Cursor  ON 

Blue 
Black 


$06        06  CURSOR  RIGHT— Moves  the  cursor  to  the 

right  one  character  position. 

$07        07  BELL— Sounds  a  bell  (beep)  through  monitor 
speaker. 

$08       08  CURSOR  LEFT— Moves  the  cursor  to  the  left 

one  character  pQiitte, 

$09       09  CURSOR  UP— Maweg  the  cursor  up  one  line. 

$0A       10  CURSOR  DOWN  (linefeed)— Moves  the 

cursor  down  one  line. 

$0C        12  CLEAR  SCREEN— Erases  the  entire  screen, 

and  homes  the  cursor  (positions  It  at  the 
upper  left  corner  of  the  screen). 

$0D       13  RETURN— Returns  the  cursor  to  the 

leftmost  character  on  the  line. 

$0E       14  DffiiPLAY  ALPHA— Switches  the  screen  from 

Graphic  mode  to  Alphanumeric  mode. 
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Graphics  Mode  Display 

Use  the  Graphics  mode  to  display  high-resolution  2-  or  4-coIor 
VDG  graphics.  The  Graphics  mode  includes  commands  to  set 

color,  plot  and  erase  individual  points,  draw  and  erase  lines, 
position  the  graphics  cursor,  and  draw  circles. 

You  must  execute  the  display  graphics  command  before  using 
any  other  Graphics  mode  command.  This  command  digpiliays  the 
graphics  screen  and  sets  a  display  format  and  color, 

The  first  time  you  enter  the  display  graphics  command,  OS-9 
allocates  a  6144-byte  display  memory.  There  must  be  at  least 
that  much  contiguous  free  memory  available.  (You  can  use 
MFREE  to  check  free  memory.)  The  system  retains  the  display 
memory  until  you  give  the  md  graphics  command,  even  if  the 
program  that  initiated  the  Graphics  mode  finishes.  Always  use 
the  end  graphics  command  to  release  the  display  memory  when 
ym  no  longer  need  the  Graphics  mode. 

Graphics  mode  supports  two  basic  formats.  The  2-color  format 
has  256  horizontal  by  192  vertical  points  (G6R  mode).  The  4- 
color  ftaroat  has  128  horizontal  by  192  vertical  points  CCJ6C 
mode).  Either  mode  provides  both  color  sets.  Regardless  of  the 
resolution  of  the  selected  format,  all  Graphics  mode  commands 
use  a  256  192  point  coordinate  system.  The  X  and  Y  coordi- 
nates axe  slLw^s  positive  numbers.  Point  0,0  is  the  lower  left  cor- 
ner of  sa?e(^. 

Many  commands  use  an  invisible  graphics  cursor  to  reduce  the 
output  required  to  generate  graphics.  You  can  explicitly  set  this 
cursor  to  any  point  by  using  the  set  graphics  cursor  command. 
"You  can  also  iBse  any  other  commands  that  include  x,y  coordi- 
nates (such  as  set  point)  to  move  the  graphics  cursor  to  the  speci- 
fied position. 

Any  graphics  function  that  draws  on  the  graphics  iere@n 
requires  that  the  VDGInt  module  is  loaded  into  memory  during 
the  system  boot. 

GrstpMes  lio^e  ielec^Qii  Codes 

Code  Format 

00  256  X  192  two-color  graphics 

01  128  X  192  four-color  graphics 
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Color  Set  and  Foreground  Color  Selection  Codes 


2-Color  Format 

4-Color  Format 

Back- 

Ibre- 

Back- 

Jbre- 

ground 

ground 

ground 

ground 

00 

Black 

Black 

IQteen 

Green 

Color 

01 

Black 

Green 

Green 

Yellow 

SetO 

02 

Green 

Blue 

03 

Green 

Red 

04 

Black 

Black 

Buff 

Buff 

Color 

05 

Black 

Buff 

Buff 

Cyan 

Setl 

06 

Buff 

Ma,genta 

07 

Buff 

Orange 

08 

Black 

Black 

Color 

09 

Black 

Dark  Green 

Set  2 

10 

Black 

Med.  Green 

11 

Light  Green 

12 

Black 

Black 

Color 

13 

Black 

Green 

Sets 

14 

Black 

Red 

15 

Black 

Buff 

Graphics  Mode  Conct^ol  Oismitiaids 


Hex  Decimal 
Control  Control 

Code      Code  Name/Fimction 


$0F        15  DISPLAY  GRAPHICS— Switches  the  screen 

to  the  Graphics  mode.  Use  this  command 
befere  any  other  graphics  commands.  The 
first  time  you  use  it,  the  system  assigns  a  6- 
kilobyte  display  buffer  for  graphics.  If  6K  of 
contiguous  memory  isn't  available,  OS-9  dis- 
plays an  error.  Follow  the  display  graphics 
command  with  two  characters  specifying  the 
Graphics  mode  and  color/color  set, 
respectively. 

$10        16  PRESET  SCREEN— Presets  the  entire 

screen  to  the  color  code  passed  by  the  XisssX 
character. 
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Hex  Decimal 
Control  Control 

Code       Code  Name/Function 


$11        17  SET  COLOR— Sets  the  foreground  color  (and 

color  set)  to  the  color  specified  by  the  next 
character  but  does  not  change  the  Graphics 
mode. 

$12        18  END  GRAPHICS— Disables  the  Graphics 

mode,  returns  the  6K  byte  graphics  memory 
area  to  OS-9  for  other  use,  and  switches  to 

Alpha  mode. 

$13        19  ERASE  GRAPHICS— Erases  all  points  by 

setting  them  to  the  background  color,  and 
positions  the  graphics  cursor  at  the  desired 

position. 

$14        20  HOME  GRAPHICS  CURSOR— Moves  the 

graphics  cursor  to  coor^nates  0,0  (the  lower 
left  comer). 

$15        21  SET  GRAPHICS  CURSOR— Moves  the 

graphics  cursor  to  the  given  x,y  coordinates. 
For  X  and  y,  the  system  uses  the  binary 
value  of  the  two  characters  that  immediately 
fdlow. 

$16       22  DRAW  LINE— Draws  a  line  in  the  fore- 

ground color  from  the  graphics  cursor  posi- 
tion to  the  given  x,y  coordinates.  For  x  and  y, 
the  system  uses  the  binary  value  of  the  two 
characters  that  immediately  follow.  The 
graphics  ■oio&g&c'  tnotes  to  IM  end  tst  ti^  line. 

$17       23  llASE  LINE— Operates  the  same  as  the 

drmv  line  function,  except  that  OS-9  draws 
the  line  in  the  background  color,  thus  erasing 
the  line. 

$18        24  SET  POINT— Sets  the  pixel  at  point  x,y  to 

the  foreground  color.  For  x  and  y,  the  system 
uses  the  binary  values  of  ^  two  ebaracters 
that  immediately  follow.  The  graphics  cursor 
moves  to  the  point  set. 
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Hex  Decimal 
Control  Control 

Code      Code  Name/Function 


$19       25  ERASE  POINT— Operates  the  same  as  the 

set  point  function,  except  that  OS-9  draws  the 
point  in  the  background  color,  thus  erasing 
the  point. 

$1A       26  DRAW  CIRCLE— Draws  a  circle  in  the  fore- 

ground color  using  the  graphics  cursor  as  the 
center  point  and  using  the  the  binary  value 
o£  the       character  as  the  radius. 

$1C       28  ERASE  CIRCLE— Operates  the  same  as  the 

draw  circle  function,  except  that  OS-9  draws 
the  circle  in  the  backgrovuid  color,  thus  eras- 
ing the  cmsiB. 

$1D       29  FLOOD  FILL— pam^s  with  the  foreground 

color,  starting  at  the  graphics  cursor  position 
and  extending  over  adjacent  pixels  having  the 
same  color  as  the  pixel  under  the  graphics 
cursor. 

Ifote:  When  yon  call  FILL  the  first  time,  it  ree(U6stg  alloca- 
tion of  a  512-byte  stack  for  the  fill  routine.  The  system  does 
not  return  this  memory  until  you  terminate  graphics  with 
the  end  graphics  command. 

Note:  The  chart  uses  hexadecimal  codes  finr  compatibility 
with  the  OS-9  DISPLAY  command. 

Display  Control  Codes  Summary 


1st  Byte 

Dec  Hex  2nd  Byte       3rd  Byte  Fvinction  

00  00  Null 

01  01  Home  alpha  ciirsor 

02  02  Column +32  Row +32       PbsitiM^  alpha  cursor 

03  03  Erase  line 
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1st  Byte 

Dec  Hex  2nd  Byte      3rd  Byte  Function 


04 

04 

Erase  to  End  of  line 

05 

(Jo 

Cursor  Code 

Alter  Cursor 

06 

06 

Move  cursor  right 

07 

07 

o     —jj-         •  ii_n 

Sound  terminal  bell 

08 

08 

TS/Tnvp  niTaftT  Ipff. 

XUUVC  i/LLX  OUl. 

09 

09 

Move  cursor  up 

10 

OA 

Move  cursor  down 

11 

OB 

Erase  to  End  of  Screen 

12 

OG 

Clear  screen 

13 

OD 

Carriage  return 

14 

OE 

Select  Alpha  mode 

15 

OF 

Mode 

Color  Code 

Select  Graphics  mode 

16 

10 

Color  Code 

Preset  screen 

17 

11 

Color  Code 

Select  color 

18 

12 

Quit  Graphics  mode 

19 

13 

Erase  screen 

20 

14 

T  T  1  '  

Home  Graphics  cursor 

21 

15 

X  Coord 

Y  Coord 

Move  graphics  cursor 

22 

16 

X  Coord 

Y  Coord 

Draw  line  to  x/y 

23 

17 

X  Coord 

Y  Coord 

Erase  line  to  x/y 

24 

18 

X  Coord 

Y  Coord 

Set  point  at  x/y 

25 

19 

X  Coord 

Y  Coord 

Clear  point  at  x/y 

2@ 

lA 

Baiditis 

Draw  drcle 

28 

IC 

Radius 

Erase  circle 

29 

ID 

Flood  Fill 
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OS-9  Keyboard  Codes 


Key  Definitions  With  Hexadecimal  Values 


NORM 

SHFT 

CTRL 

NORM 

SHFT 

CTRL 

NORM 

SHFT 

CTRL 

0 

30 

0 

30 

— 

@ 

40 

60 

NUL  00 

P 

70 

r  OU 

T\{  1?    1  A 

JJljJii  lU 

1 

31 

I 

21 

1 

7C 

a 

61 

A 

41 

SOH  01 

q 

71 

y  51 

UL-l  11 

2 

32 

22 

00 

b 

62 

B 

42 

STX 

02 

r 

72 

i\  DZ 

3 

33 

# 

23 

7E 

c 

63 

C 

43 

ETX  03 

s 

73 

S  53 

DC3  13 

4 

34 

$ 

24 

00 

d 

64 

D 

44 

EOT  04 

t 

74 

T  54 

DC4  14 

i 

as 

% 

25 

00 

e 

65 

£ 

45 

EMD05 

u 

75 

U  55 

NAK15 

f 

m 

& 

23 

00 

f 

66 

F 

46 

ACK06 

V 

76 

V  56 

SYN  16 

7 

m 

2f 

5E 

g 

S7 

6 

if 

m 

77 

W  57 

M5S  17 

a 

38 

c 

28 

I 

5B 

h 

68 

H 

48 

BSP 

08 

z 

78 

X  58 
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Appendix  D 


OS-9  Keyboard  Control 
Functions 


Key  D^tnitions  for  Special  Functions  and  Characters 


Key 
CMopAKiiUitliin 


ContrdI  Fnnciiiiii  or  dliaractcr 


Alternate  — fette  high  ^rder  bit  on  a 
ehaa^act^.  Fxem  fin  char. 


rCTHLl 


I  snmi  or  fCTRnni 

fCTRLl  GD 


[mJlZI 

I  CTRL  II  BREAKI 


H  or  [cranrHl 


SHIFT  -*-  or 


CTRL  X 


SHIR   BREAK  Or 


[ctrO(c] 


I  CTRL  |(T1 


CTRL  1 


CTRL  3 


CTRL  7 


CTRL  8 


Use  as  a  control  k^. 

Stops  the  program  ciirrently  executing. 

Generates  «a  uzidearscore  L-). 

Generate  a  Ml  hv@m  ({}• 

Gen^ates  a  right  brace  Q). 

Generates  a  revise  slash  (\). 

Generates  an  end-of-file  (EOF).  This 
sequence  is  the  same  as  pressing  |  esc  |  on  a 
standard  terminal. 

Generates  a  backspace. 

Deletes  the  entire  current  line. 

Interrupts  the  video  display  of  a  running 
program.  This  s#(|tience  reactivates  the 
shell  and  then  runs  the  program  as  a  bai^- 

ground  task. 

Upper-Zlowercase  shift  lock  function. 
Generates  a  vertical  bar  (|)  in  reverse  video. 
Generates  a  tilde  (')  character. 
Grenerates  an  up  arrow  or  caret  C). 
Generates  a  Mt  bracket  ([). 
Grenerates  a  right  bracket  (]). 


OS-9  Commands  Ueference 


j\ey 
Combination 

Control  Function  or  Character 

1  CTRL  II  A  1 

Repeats  the  previous  command  Une. 

1  CTRL  II  D  1 

Redisplays  the  command  line. 

1  CTRL  II  W  1 

I  unit.  11  »■  J 

Temporarily  halts  output  to  the  screen. 

Press  any  key  to  resume  output. 

1  CTRL  II  CLEAR  | 

Enable/Disable  K^board  mouse. 

1  CLEAR  1 

Change  screms. 

1  SHIF  II  CLEAR  | 

Change  screens  in  reverse  order. 

1  ENTER  1 

D-2 


ACIAPAK  5-6,5-7,6-96 
active  state  4-2 
address  2-4 

memory  4-5 
allocate  memory  for  devices 

6-55 
alpha  mode  B-3 

select  B-10 
alphanumeric  mode  B-1 
ampersand  separator  3-6 
append  files  6-68 
application  program  1-3 
arglist  6-2 
ASCII  2-5 

control  characters  B-1 

convert  6-38 
ASM  3-2 
asterisk,  editor  7-3 
ATTR   2-10,  6-5 
attribute    2-5,  2-8,  2-10,  6-5 
auto-answer  modem  6-96, 
6-108 

Ittuikground 

color  B-7 

process  3-7 

task  4-1 

screen  6-2 
backspace  6-93 

character   6-94,  6-106, 
6-107 

editor  7-2 

over  line   6-93,  6-106 
BACKUP    5-4,  6-7 
backup  a  directory  6-39 
BASIC09    2-5,  2-6,  3-13,  B-1 
baud  rate   5-4,  5-5,  5-6,  6-96, 

8-98,  6-109 
begin  a  window  6-103 
bell 

character  6-95,  6-108 
sound  B-10 


bit  2-1 

stop    5-5,  5-6 

user  2-11 
bitmap  2-5 
block 

number  4-5 

devices  1-2 
bootstrap  5-1 

file  5-2 
box  graphics  B-3 
brackets  6-3 
buffer  3-7,7-2 

edit  7-1 

secondary  7-1 

text  7-1 
BUILD   2-6,  3-10,  6-10,  6-71, 
6-75 

bidlt'in  »»nzaands  3-1,  3-11 
byte  2-1 

carriage  return  B-10 

CC3Disk  5-1 

CC3Go  5-2 

CC3I0    5-1,  B-2 

chaining  programs  6-44 

change 

attributes  2-10,  2-11 
directory   6-12,  6-91, 

6-84 
file  name  6-84 
priority  3-12,6-88 
system  parametars  6-93 

character 

ASCII  2-5 
delete  6-107 
devices  1-2 
backspace  6-94,  6-106, 

6-107 
bell    6-95,  6-108 
delete  line   6-94,  6-107 
dup  6-95,6-107 
end-of-file  6-94,6-107 
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character  (cnnt'c]) 

prnnTnanH  podpci 

pTiH-of-ypooTrl  fi-Q4 

6-107 

P'fanViip^  R-V 

gx  cxLyxxx^o       xj  1 

L'UXXXXXXdlXLLLlCliJ.lC       \J  £i 

wUXXXXXXClXXU.  o 

quit   6-95,  6-108 

ASM  3-2 

renrint    6-95  6-107 

ATTR    2-10  2-11  fi-5 

xXX  X  Xv        ^            J    ^    J~  J.  J    \J  tj 

terminate    6-95  6-108 

BACKUP  6-7 

nnnprpfisp  R-2 

BIJTTjn    2-6  3-10  6-10 

CHD   3-11  6-12 

6-71  6-75 

pVippIc  fli^^V  cifmptnyp 

UU.il  L~  1x1       (J   X.  X 

CHD    3-11  6-19 

V^XXXJ       tJ"X  X  J  \J~  A.£i 

CHX    3-11  fi-12 

CHX    3-1 1   fi-1  9 

v^XX^      O  X  X ,  U  XiSt 

pitpIp 

CMP  6-14 

UX  d-Vy  *J«i^ 

COBRTiTCP    fi-lfi  fi-79 

\J\Jl  tl  II  JI'JXV       U"XUj  U~  1  i&i 

erase  B-9  B-10 

CONFIG   5-2  5-3  5-4 

clear 

6-18 

srrppn  R-fi 

COPY    2-3  3-6  4-8  6-22 

t.n  PTiri-nf-linp 

VV  ImUU  UL  XXXXC  XJ~*X 

DATE  6-24 

clbclc  5-2 

X^  VyXXXJ\,>X\.       U:  At/ 

rliister    2-4  2-5 

1-/XJX1N  X/J  LI"uU 

CMDS  directory    5-1  5-3  5-4 

\_vi¥XX-/kJ  UXXC^LUXjr        (J           U  <Jj 

DFJ,  6-31 

CMP  6-14 

DEIiDaB  2-3  6-S3 

COBBTjER    6-lfi  6-72 

DTP    9-6  9-9  8-3^1 

code 

DTSPTjAY  6-38 

X./XkJX  1  i  ii  1         u  oo 

alT)ha  mode  conti*ol  B-4 

DSAVE  6-39 

cursor  B-fi 

DUMP   2-8  6-72 

FdTfj  fe41 

^USX  LXIJil  JLfdlLldXl; 

CUIU  llidLX  U        1  "AO 

Ul|xUx 

XLxVxvV^XV      0"^j  D~frO 

HflplrcrrfmnH  B-Y 

lii/C4.V'*VgX.  U  Uli,U       JLJ~  1 

*U£^      O"  X  X,y  VI 

iUx  Cgl  UUIiU      JJ-  (  J  Jj-O 

i3CXCL>L       iJ  ±.\J 

X'  XVXJXlJ      u to 

co^    CTvcinri  if^G  R_7 
OCLj  gX  d^xXii^iS       XJ  f 

rtP,T  9-fi 

pfYmV»inp  filpci  R-fi8 

VUXXXItJXlXC^  XXXCS       KM  \J\J 

HFTjP  6-51 

XXXJXJX         \J  tj  A. 

fiotmnfinH 

WXXXXX  XCIfXXU 

i  3-11 

groupfnf  3-i,  3-9 

IDENT  3-3,6-52 

help  6-51 

INIZ  6-55 

interpreter  6-90 

J\1LL    0-lz,  b-ob 

line   3-1,  3-2 

LINK  6-58 

parameters,  editor  7-3 

LIST  2-3,2-5,2-8,3-4, 

separator  3-1,  3-5 

6-59 

summary,  editor  7-56 

LOAD  4-7,6-61 

1 

Index 


commands  {cont'd) 

MAKDIR  2-3,2-11, 

6-63 
MDIR  6-64 
MERGE  6-68 
MFREE  6-69 
MODPATCH  6-70 
MONTYPE  6-74 
0S9GEN  5-2,5-3,6-76 
p  3-12 

PROCS  3-7,4-2,6-80 

PUT  2-6 
PWD  6-82 
PXD  6-82 
RENAME  6-84 
RUNB  3-13 
SEEK  2-6 
SETIME    5-3,  6-86 
SETPB  3-12,6-88 
^LL  3-6,6-90 
t  3-12 
TMODE  6-93 
TUNEPORT  6-98 
UNLINK  4-7,4-8, 

6-100 
w  3-12 

WCREATE  6-103 
X  3-12 

XMODE  5-4,5-5,5-7, 
6-106 

comment,  in  a  program  3-12 
compare  files  6-14 
concurrent 

execution   3-5,  6-91 

mode  3-10 

process  3-9 

task  4-1 
CONFIG   5-2,  5-3,  5-4,  6-18 
control 

characters,  ASCII  B-1 

keys,  editor  7-2 
convert  to  ASCII  6-38 
COPY   2-S,  3-6,  4-8,  6-22 


coRy 

a  directory  6-39 

diskettes  6-7 
CPU  4-1 

prittrily  6-88 
CRC  2-7,6-71 
create 

a  directory  6-63 

a  file  6-10 

OS9Boot  6-16,6-76 

process  3-6 

system  diskette   5-3,  5-4, 
6-16,  6-18,  6-76 

current 

directory   4-4,  6-12 

processes  6-80 
cursor 

on/off  B-5 

codes  B-5 

control  B-1,  B-4 

graphics   B-6,  B-8 

home  B-4 

move   B-5,  B-10 
cyclic  redundancy  checksum 
2-7 

data  format  2-1 
iata  otttpit,  halt  7-3 
delta 

redirect  3-4 

input/output  1-2 

passing  4-4 

process  2-1 

sending  2-1 

transfer  2-1 
DATE  6-24 
date  2-5 

set  6-86 
day  6-2 
DCHECK  6-25 
deallocate  a  device  6-30 
DEINIZ  6-30 
DEL  6-31 
delay,  not  ready  5-6 
DELDIR   2-3,  6-33 
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delete 

a  character  6-107 
a  directory  6-33 
a  line  7-3 

a  memory  module  4-7, 

6-100 
files  6-31 
line  character  6-94, 

6-107 
lines,  editor  7-10 

descriptor 

device  1-2 
file  2-3 

detach  a  device  6-30 

device 

allocate  memory  6-55 
block-oriented  1-2 
character  1-2 
deallocate  6-30 
deseriptor  1-^2,  5-1 
driver    1-2,  2-1,  5-1 
driver  initialization 
6-55 

name  2-12,  2-13 
window  2-12-  2-13 

devname  6-2 
DIR   2-6,  2-9,  6-35 
directory   2-2,  2-3 

attribute  2-8 

change  6-12,  6-91 

change  name  6-84 

CMDS   5-1,  5-3,  5-4 

copy  6-39 

create  6-63 

current   4-4,  6-12 

delete  6-33 

list  6-35 

naodule  4-6 

OMwrship  2-8 

SYS  5-1,5-4 

view  6-82 

working  6-12 
dirname  6-2 
disable  echo   6-94,  6-107 


disk 

cluster  2-4 
file  2-3,2-4 
I/O  3-8 

initialization  6-46 
nanaes  2-12 
ownership  2-8 
sector  2-4 

structure,  check  6-25 
tsm  VO  3-8 
unused  sectors  6-49 

diskette 

copy  6-7 
density  2-5 
tracks  2-5 
system  2-2 

DISPLAY  6-38 

display 

a  directory  6-35 
current  processes  6-80 
date  and  time  6-24 
error  message  6-43 
essecution  directory  6-82 
file  Qontesits  6-59 
free  memory  6-69 
graphics  B-7 
help  6-51 

memory  module  names 
6-64 

messages  6-42 

on  next  line  7-2 

text,  editor  7-6 

xmused  disk  sectors  6-49 

working  directory  6-82 
double  density  2-5 
draw 

a  circle  B-9 

aline   B-8,  B-10 
drivers,  device  i-2 
DSAVE  6-39 
DUMP   2-8,  6-72 
dup  character    6-95,  6-107 
duplicate 

last  line  6-95 

line  6-107 


Index, 


ECHO  6-42 
echo  6-92 

enable/disable  6-94, 

6-  107 

edit 

buffer  7-1 

commands,  EDIT  7-6 
pointer   7-1,  7-2,  7-7 

EDIT,  editor  7-5 

editor  7-1 

backspace  7-2 
command  summary 

7-  55 

command  syntax  7-4 
commands  7-2 
control  keys  7-2 
delete  lines  7-10 
error  messages  7-59 
getting  started  7-4 
insert  lines  7-10 
interrupt  7-3 
numeric  parameters  7-3 
quick  reference  7-55 
searching  7-13 
substituting  7-13 
terminate  7-2 
text  file  operations  7-18 
using  the  asterisk  7-3 
dlipsis  6-3 

enable  echo   6-94,  6-101 
end  graphics  B-8 
end-of-file 

terminate  7-2 

character  6-94,  6-101 
end-of-line 

clearing  B-4 

erase  B-10 
end-of-record  characti^  6-94, 

6-107 
erase 

a  circle    B-9,  B-10 
a  line  B-10 
graphics  B-8 
line   B-4,  B-8,  B-9 
point  B-^ 


^ase  {cont'd) 

to  fflid-of-llne  B-10 
Errmsg  5-2 
ERROR   5-2,  6-43 
error  i-Il,  6-92 

message  file  5-2 

messages,  editOT  f-59 

output  6-91 

path  3-4 
establish  a  directory  6-63 
EX  3-11,6-44 
exclamation  mark  separator 

3-8 
execute 

a  program  6-90 

permission   2-9,  2-10 
execution 

concurrent    3-5,  6-91 

modifier   3-1,  3-3 

sequential   3-5,  3-6,  6-91 

fields  2-6 
file   2-2  -  2-4 

attribute  2-8 

change  name  6-84 

compare  6-14 

copy  6-22 

create  6-10 

delete  6-31 

descriptor  2-3 

descriptor  sector  2-5 

display  contents  6-59 

bad  in  memory  6-61 

merge  6-68 

manager  5-1 

OS9Boot  5-4 

ownership  2-8 

pointer  2-4 

pracedure   2-6,  3-10, 
3-11 

random  access  2-6 
security  2-8 
single-user  2-8 
size  2-5 


5 


OS-9  Commands  Reference 


file  (cont'd) 

Startup    2-6,  5-1,  5-3, 
5-4 

text  2-5 
fiknme  2-3,  6-2 
fill  portion  of  screen  B-9 
flood  fill   B-9,  B-10 
floppy  disk  names  2-12 
fonts  5-2 

ifereground  color  B-7,  B-8 
fork  3-7,4-6 

request  4-3 
FORMAT  6-46 
FREE  6-49 

generate  messages  6-42 
GET  2-6 

getting  started,  editor  7-4 
graphic  window  fonts  5-2 
graphics  B-1 

color  set  B-7 
command  codes  B-7 
cursor   B-6,  B-8 
mode,  select  B-10 
end  B-8 
erase  B-8 

medium  resolution  B-6 
VDG  B-6 
group  2-7 

grouping,  commands  3-9 

halt  data  output  7-3 
hardware  1-2 
header 

information  6-52 
module    2-7,  3-3,  4-7 

HELP  6-51 

hefc  6^2 

hexadecimal  code  displ^ 

6-38 
home 

alpha  cursor  B-9 
eamoT  B-4 
hours  6-2 


I-code  3-13 
I/O 

paths  3-4 

transfers  3-8 

raw  i-S 
ID,  process  4-4 
IDENT   3-3,  6-52 
images,  pointer  5-2 
immortal 

procesfs  6-01 

shell  3-11 
INIT  5-1 
initialize 

a  disk  6-46 

a  window  6-108 
INIZ  6-55 
input  2-1 

lines  3-12 

path  3-4 

redirect  0-91 

standard  4-4 
insert  lines,  editor  7-10 
interpreter,  ^nmaands  6-90 
intit|«'Oeess  communication 
3-7 

interrupt  editor  7-3 
lOMAN  1-2,1-3,5-1 

kernel    1-1,  1-2 
keyboard  1-1 
keyword    3-1  -  3-3 
KILL  6-56 
kill  3-12 

a  directory   6-33,  6-33 

files  6-31 

length 

of  video  page  6-94 
word   5-5,  5-6,  6-96, 
6-109 

line 

backspace  6-93,  6-106 
delete,  editor  7-8 

draw    B-8,  B-10 
duplicate  6-95 


Index 


line  (fiortfcD 

duplicati<m  6-107 
erase    B-4,  B-8,  B-9, 

B-10 
syntax  6-1 

linefeed  6-94,  6-107 

lines,  command  3-1 

LINK  6-58 

LIST  2-3,  2-5,  2-8,  3-4,  6-59 
list 

a  directory  6-35 
current  processes  6-80 
memory  module  names 

6-64 
sepnent  2-5 
with  program  files  2-8 

LOAD   4-7,  4-7,  6-61 

lock  a  module  6-58 

lockout  2-11 

b^cal  sector  2-3, 2-4 

lowerease   6-93,  6-106 
characters  B-2 

machine  language  3-12 

macro  testt  edftoa-  7-1 

macros,  edit  7-25 

MAKDIR  2-11,2-3,6-63 

jfiMQiigemeait,  memory  4-5 

manager 

pipe  1-i 
random  block  1-2 

mark  space   6-95,  6-108 

MDIR  6-64 

MDMkill  5-6,5-7 

medium  resolution  graphics 
B-6 

memory 

address  4-5 
allocation  3-1 
display  free  6-69 
load  a  file  into  6-61 
management    1-1,  4-5 
size  modifier  3-3 

m^ory  modi;des 
tock  @-<68 


menKH^  modules  iconfd) 
unlink  6-100 

deleting  4-7 
display  names  6-64 

MMBm  6-68 

messages  with  ECHO  6-42 

messages,  error  6-48 

MFREE  6-69 

minutes  6-2 

MMU  4-5 

mode,  alpha  B-3 

mode 

alphanumeric  B-1 

concurrent  3-10 

semigra^c  B-1 
modem   1-1,  5-6,  5-7 

auto-answer  6-108 

name  2-12 
modifier   3-1  -  3-3 

execution  3-1,  3-3 

memory  size  3-3 

redirection  3-5 
modname  6-2 
MODPAK  5-7 

MODMTCH  8-70,  6-71,  6-72, 

6-73 
module  1-3 

deleting  memory  4-7 

directory  4-6 

header   2-7,  3-3,  4-7 

header  information  6-52 

loading  4-7 

Iodic  in  memory  6-58 

primary  4-3 

program  2-7 

unlink  4-8 
month  6-2 

MOIOTM  6-74,6-75 
move  cursor   B-4,  B-5,  B-10 
multiprogramming  4-1 
multitasking  1-1 

name 

device   2-12, 2-13 
modem  2^12 
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name  (cont'd) 

printer  2-12 

program  3-3 

terminal  2-12 
next  line,  display  7-2 
not  ready  del^  5-6 
notations,  »|:atax  6-1 
null  count  6-94,  6-107 
number 

priority  3-12 

user   2-8,  4-4 
numeric  parameters,  editor 
7-3 

object  code  2-7 
operating  system  1-3 
opts  6-2 
OS9Boot   5-1,  5-4 

create   6-16,  6-76 
0S9Gen   5-2,  5-3,  6-72,  6-76 
OS9p2  5-1 
output  2-1 

error  6-91 

path  3-4,4-4 

redirect  3-11,6-91 
owner  2-5,  2-8 

page  length,  video  6-107 
pages  3-3 

parameter   3-1,  4-4 

change  system  6-93 
command  editor  7-3 

paramlist  6-2 

parent  process  4-2 

parity   5-6,  5-7,  6-95,  6-108 

passing  data  4-4 

pathlist  6-2 

paths  2-1 
FO  3-4 
output  4-4 
Standard   3-4,  6-93 

patterns,  semigraphic  B-2 


pause  6-94 

characta*  ft-flj  8-108 

screen  6-107 
permission  6-2 

execute   2-9,  2-10 

read  2-9,  2-10 

wr^.  iJ,  i»lO 
jdiysical  sector  2-4 
PIC  4-8 

pipe   1-2,  3-7,  5-1 
pipelines   3-7,  3-8 
PDMAM  S^l 
Piper  5-1 
point 

erase  B-9 

set  B-8,B-10 
pdnter 

edit  7-1,7-2 

editor  7-7 

file  2-4 

images  5-2 
port  1-2 

port,  RS-232  5-4,6-109 
position  alpha  cursor  B-9 
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Chapter  1 


Looking  at  the  Basics 


BASIC09  is  a  computer  language  created  for  use  with  the  OS-9 
operating  system.  Along  with  standard  BASIC  language  state- 
ments and  functions,  it  includes  the  most  useful  elements  of  the 

PASCAL  computer  language. 

In  brief,  BASIC09's  advantages  are: 

Fast  execution  speed     BASIC09  compiles  procedure  lines  as 

you  enter  them.  When  you  finish  a 
procedure,  you  can  compile  it  further. 
The  result?  Procedures  that  execute 
nearly  as  &st  as  machine  language. 

Full  feature  editing      The  text  editor  features  automatic  line 

formatting,  search,  search  and  change, 
global  search,  global  search  and 
change,  line  renumbering,  and  much 
more.  You  can  move  in  and  out  of  the 
editor  quickly  and  easily. 

You  can  write  small,  easy-to-under- 
stand  procedures,  then  chain  them  to 
create  sophisticated  programs,  ^u  can 
call  one  procedure  from  another, 
regardless  of  whether  the  called  proce- 
dure is  in  memory  or  on  disk. 

Both  you  and  your  procedures  can 
take  advantage  of  almost  any  OS-9 
function  from  within  BASIC,  including 

the  execution  of  disk  management 
commands  and  application  programs. 

You  can  structure  procedures  more 
efficiently  and  clearly  by  taking  advan- 
tage of  a  variety  of  loop  commands, 
optional  line  numbering,  and 
BASIC09's  ability  to  call  modules, 
written  in  other  computer  languages. 


Modular 
programmiTig 


Inter£acing  to  OS-9 


Structured 
programming 
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Memory  saving 
features 


Complex  data 
structures 


Sophisticated 
graphics 


High  speed, 
precision  math 


Simple  and  £ast 
debugging 


Strings  can  be  any  length.  For  each 
operation,  you  can  select  the  most  effi- 
cient of  five  available  data  "^^s.  Com- 
piled procedures  use  less  space.  You 
can  save  several  procedures  into  one 
file. 

Combine  any  type  of  data  into  a  single 
dimensioned  data  staructure  that  you 
can  move,  store>  ami  as$ipi  effisi^  and 
quickly. 

BASIC09  has  three  levels  of  graphics. 
The  high  resolution  graphics  and  text 
capabilities  feature  more  than  50 

functions. 

BASIC09  has  a  full  range  of  fast  and 
accurate  math  and  transcendental 

capabilities  including  powers,  roots, 
trigonometry,  logic,  and  Boolean 
functions. 

BASIC09  provides  superior  debugging 
functions.  It  checks  syntax  as  you 
enter  lines.  It  points  to  the  location  of 

your  errors  and  tells  you  what  they 
are.  You  can  stop  programs,  enter  the 
debugger,  then  continue  execution. 
Execution  errors  automatically  put  you 
in  a  debugging  mode  where  you  can 
examine  values,  and  step  and  trace 
your  way  through  faulty  procedures. 


Using  Bi^^09 


Befiare  anything  else,  make  a  backup  copy  of  your  BASIC09/ 
CONFIG  diskette.  You  can  do  this  using  the  BACKUP  command. 
If  you  are  not  familiar  with  BACKUP,  see  Chapter  3  of  Getting 
Started  With  aS-5. 

To  use  BASIC09,  boot  your  computer  as  described  in  Getting 
Started  With  OS -9.  Replace  the  systom  diskette  in  Drive  /DO 
with  the  BASIC09/OOHFI@  )m^33^  diskette  t^: 


baalcgaliNTlRl 
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After  a  short  pause,  during  which  OS-9  loads  BASIC09  from  the 
diskette,  the  screen  displays  the  copyright  and  a  new  prompt, 
like  this: 

BAS I C09 
RS  VERSION   01 .00.01 
COPYRIGHT  1980  BY  MOTOROLA  INC. 
AND  MICROWARE  SYSTEMS  CORP. 
REPRODUCED  UNDER  LICENSE 
TO  TANDY  CORP. 
ALL  RIGHTS  RESERVED 

Bas  ic09 

Ready 

B: 

The  B:  indicates  that  your  computer  is  in  the  BASIC09  command 
mode.  From  the  command  mode,  you  can  issue  instructions  to 
the  system  executive  to  manipulate  procedures  (programs). 

Requesting  More  Memory 

Unless  you  specify  otherwise,  BASIC09  automatically  sets  aside 
8192  bytes  of  memory  as  a  workspace  into  which  you  can  type  or 
load  procedures.  BASIC09  reserves  apprfflimately  1200  bytes  of 
the  workspace  for  internal  use,  leaving  you  with  6992  bytes  for 
workspace. 

There  are  two  ways  to  set  aside  more  memory  for  BASIC09 
operations: 

•  You  can  reserve  extra  memory  when  you  first  enter 
BASIC09  by  using  the  OS-9  memory  size  option.  For 
instance,  to  reserve  18,176  Igrtes,  enter  this  command  to 
initialize  BASIC09: 

basic  09  mm  I  ENTER  | 

•  You  can  also  request  additional  memory  after  loading 
BASIC09.  At  the  command  prompt,  B : ,  type: 

mem  1  8000  |  ENTER  | 

This  tells  BASIC09  to  set  aside  a  total  of  18,000  bytes  of 
memory,  if  they  are  available. 
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In  both  cases,  because  BASIC09  rounds  the  amount  you  request 
to  the  next  multiple  of  256,  the  actual  reserved  memory  is  18176 

Note:  If  your  system  does  not  have  enough  free  memory  to 
reserve  the  amount  you  specify,  the  workspace  size  does  not 
change. 

You  can  also  use  the  MEM  command  to  reduce  memory.  How- 
ever, BASIC09  does  not  reduce  the  size  of  the  workspace  if  doing 
so  destroys  resident  procedures. 

Writing  Procedures 

BASIC09  is  a  modular  programming  language.  Several  proce- 
dures can  occupy  memory  at  the  same  time.  Each  procedure  per- 
fixrms  a  particular  function  but  can  also  interact  with  others  to 
form  a  sophisticated  program. 

To  create  or  change  procedures,  enter  the  edit  mode  by  typing 
either  edit  |  enter  |  or  [T]  |  enter  |  at  the  B :  prompt.  From  now  on, 
when  directing  you  to  @iiter  the  edit  mode,  this  manual  uses  the 
easier  to  type  [e]  OESxmand. 

Each  time  you  t^e  a  procedure  line  and  press  [  enter  |,  the  editor 
checks  for  common  errors.  This  automatic  checking  lets  you 
catch  mistakes  before  you  run  the  program,  saving  you  testing 
and  rewriting  time.  You  can  even  let  the  automatic  checking 
help  ym  learn  the  rules  of  BASIC09.  If  you  are  not  sure  about  a 
syntax,  go  ahead  and  type  it  the  way  you  think  is  correct.  If  you 
guess  wrong,  BASIC09  shows  where  the  error  is  and  displays  a 
message  to  tell  what  is  wrong. 

BASIC09's  use  of  modules  lets  you  divide  large  and  complex  proj- 
ects into  smaller,  easily  manageable  sections.  Not  only  are  the 
smaliear  procedures  easier  to  write  and  understand,  they  are  also 
easier  to  test.  As  well,  because  BASIC09  lets  you  call  procedures 
that  are  outside  the  workspace  (the  computer's  memory  where 
you  write  and  edit  procedures),  you  can  accumulate  libraries  of 
procedures  to  incorporate  into  future  programs. 

You  can  work  on  a  program's  procedures  either  individually  or 
as  a  group.  Fbr  example,  te  -maeh.  tm.  the  procedures  as  a  gmuf, 
save  your  workspace  procedures  into  a  single  disk  file.  When  you 
subsequently  load  the  file,  BASIC09  automatically  loads  all  of 
the  procedures. 
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Modules  of  Other  Languages 

BASIC09  can  incorporate  procedures  from  other  languages,  such 
as  Pascal,  C,  or  assembly  language.  Several  users  can  then  share 
the  procedures. 

Executing  Procedures 

"5^)11  execute  or  run  programs  from  the  command  mode.  When 
you  enter  a  procedure,  BASIC09  compiles  it.  This  means  that  the 
procedure  is  ready  for  execution  as  soon  as  you  exit  the  edit 
mode.  Jbr  instance,  if  you  create  a  program  named  Greeting, 
you  can  ess^iute  it  hy  typing  fmm  fte  mimmmSi-  ffisiei 

run  greeting  |  ENTER] 

Leaving  BASIC09 

There  are  two  ways  you  can  exit  from  BASIC09: 

•  At  the  B ;  prompt,  t3?pe: 

bye  I  ENTER  | 

•  Or,  at  the  B :  prompt,  press  I  CTRL  ||  breakI. 

When  you  use  either  method,  the  OS-9  prompt  appears  immedi- 
ately indicating  that  the  operating  system  is  waiting  for  a 
command. 

Note:  When  you  exit  BASIC09,  yoru  lose  all  procedures 
residing  in  the  workspace.  Be  sure  to  save  them  on  disk 
before  leaving  BASIC09. 

The  Keyboard  and  BASIC09 

You  can  use  some  keys  and  key  sequences  to  produce  special 
characters  and  to  accomplish  special  BABIC09  functions.  You  ini- 
tiate a  sequence  hy  pressiaag  Me  fe^  and  holding  it  §mm. 
while  pressing  a  second  key.  The  foltowing  list  summarizes  your 
keyboard's  special  functions: 


Produces  graphic  characters.  Press  |  alt|  char 
where  char  is  a  keyboard  character). 

A  control  key  that  you  use  with  other  keys. 
Cieeh^iW,) 

Stops  the  et^rrent  program  emcutiaa  and 
returns  to  the  B:  prompt  in  BASIC09's  com- 
mand mode. 

Moves  the  cursor  back  one  space. 

Produces  an  underscore  character. 

Produces  a  left  brace  (<). 

Produces  a  right  brace  (>). 

Produces  a  tilde  (~). 

Produces  a  backslash  (\). 

Performs  an  ESCAPE  fun^eia  and  secsii  an 
end-of-file  messtfe  to  a  program  receiving 
k^board  input.  TS  be  recognized,  |  ctrl  ||  break  | 
must  be  the  first  thing  l^ed  on  a  line. 

Stops  execution  of  a  program  and  causes 
BASIC09  to  enter  the  Debug  mode. 

Displays  the  next  window. 

Displays  the  previous  window. 

Deletes  the  current  line. 

Activates  cb*  deactivates  the  shift  bck  function. 
Produces  a  vertical  bar  ( | ). 
Produces  an  up  arrow  (♦). 
Produces  a  left  bracket  ( [). 
Produces  a  right  bracket  (l). 
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I  CTRL  IfTI  Redisplays  the  last  line  typed,  and  positions 

the  cursor  at  the  end  of  the  line,  but  does  not 
process  the  line.  Press  I  enter  |  to  process  the 
line,  or  edit  the  line  by  backspacing.  If  you 
edit,  press  I  ctrl  IfT]  again  to  display  the  edited 
line. 

I  cm  IIP  I  Redispl£^s  the  curr^t  command  line. 

I  CTRL  Ifwl  Temporarily  halts  video  output.  Press  the 

space  bar  to  resume  output. 

I  ENTER  I  Performs  a  carriage  return  or  executes  the 

current  command  Hne. 
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Chapter  2 


Sample  Session 


Although  BASIC09  has  several  functions  or  modes,  they  all  work 
together  to  make  programming  as  simple  as  possible.  The  easiest 
way  to  learn  how  BASIC09  and  its  functions  operate  is  to  write 
and  run  a  program.  This  chapter  provides  sample  statements 
and  instructions  to  help  you  learn  how  to  use  BASIC09. 

To  create  and  execute  a  program: 

1.  Load  BASIC09  and  enter  the  edit  mode. 

2.  Type  the  BASIC  program. 

3.  Enter  the  system  mode  and  test  the  program's  e^cution. 

4.  Debug  the  program.  (Correct  any  programming  errors.) 

5.  Save  the  completed  program  on  disk. 

6.  Load  the  program  into  memory  and  use  it. 

To  begin  the  program,  execute  BASIC09.  To  be  sure  you  have 
enough  room  in  which  to  work,  reserve  a  workspace  of  10,000 
bytes  by  ^ia^: 

basicBS  #iaK  flfllRl 

The  BASIC09  system  mode  prompt,  Bi,  appears  after  the  tsopy- 
right  message.  In  the  system  mode,  you  can  do  such  things  as 
save  and  load  procedures,  change  workspace  size,  and  rename 
and  delete  procedures. 

Creating  a  Procedure 

To  write  procedures,  you  must  be  in  the  edit  mode.  You  get  there 
by  typing: 

e  I  ENTER  | 

IMs  causes  the  screen  prompt  to  change  to  E  :,  and  screen 
di^lays: 

PROCEDURE  Program 

Because  you  didn't  give  a  program  name  when  you  entered  e, 
BAS[C09  selects  the  name  Program  for  you.  Now,  you  must 
write  the  code  to  make  Program  do  something. 
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Commands  and  Program  Lines 

There  are  two  responses  you  can  give  at  the  edit  mode  prompt. 
You  can  type  an  edit  command,  or  you  can  type  a  program  line. 
If  you  type  a  program  line,  yam  must  type  a  ipace  as  the  first 
character  in  the  line.  If  you  type  an  edit  command,  do  not  pre- 
cede it  with  a  space.  To  make  listings  easier  to  read,  this  man- 
ual uses  the  symbol  □  to  indicate  spaces  before  every  line.  It  also 
uses  the  D  symbol  in  some  procedure  lines  to  indicate  the  correct 
axunbgr  ^  ^Bism  pseded.  Wimm&it  ym  &m  eltte  a  space  at  a  0 
symbol  in  a  pj^oeechiie  ym  am  ty^xig,  press  I3m  tar. 

To  type  the  procedure  in  this  chapter,  begin  each  line  at  the  E : 
prompt.  After  typing  a  line,  check  it  for  mistakes.  If  you  make  a 
mistake,  use  Q  to  move  the  cursor  back.  Correct  the  mistake. 
Then,  type  the  remaining  portion  of  the  line.  If  there  are  no  mis- 
talees,  press  |  enter  |. 

BASICOQ  checks  eiach  line  when  you  press  [  enter  |.  If  you  make  a 

mistake  in  syntax  or  form,  BASIC09  displays  an  error  message. 
An  arrow  points  to  the  place  in  the  program  line  where  the  error 
occurred,  and  a  message  number  indicates  the  type  rf  error. 
Refer  to  Appendix  A  for  an  explanation  of  the  error  codes. 

If,  after  you  enter  a  line,  you  find  that  you  made  a  mistake,  type 
d  I  ENTER  I  to  delete  the  line.  Then,  retype  the  Line.  Later,  the  imi&- 
ual  tells  you  how  to  change  text  in  ^stii^  lines. 

The  following  program  helps  you  do  a  bit  of  arithmetic.  To  get  a 
feel  for  BASIC09,  tj^e  and  execute  the  program  as  directed. 
Bemember,  when  you  see  either  a  space  or    press  the  space  bar. 

□DIM  NUMBER1  ,NUMiEI?2j INTEGER 
□  INPUT  "Type  Number  ..." -.NUMBER! 
□INPUT  "Type  another ...." ;NUMBER2 
□PRINT  "The   sum  of   the  numbers   is...  "; 
□PRINT  NUMBER1    +  NUMBER2 
□END 
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Executing  a  Procedure 

To  execute  the  procedure,  quit  the  edit  mode  by  typing  q  |  enter  |. 
The  compiler  further  processes  your  procedure,  and  the  B: 
prompt  reappears.  To  execute  the  program,  type: 

run  I  ENTER  I 

Tj^e  in  numbers  when  asked,  and  the  procedure  produces  their 
sum.  If  you  want  to  save  the  program  on  disk,  the  n^t  chapter 
tells  you  \imf  .  Chapter  4  intediie^  several  t^kmc  e^t  mode  com- 
mands to  search,  display,  insert,  and  change  programs  lines  and 
text. 
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The  System  Mode 


1*he  BASJ309  command  irderpreter  processes  system  cctmmands. 
At  the  B :  prompt,  you  can  enter  system  commands  in  either 
upper-  or  lowercase  letters.  Some  commands  operate  on  the  pro- 
cedures in  the  workspace.  Others  provide  functions  independent 
of  any  procedures.  Following  is  a  list  of  all  system  ccanmands 
and  their  purposes. 


Command 


$ 


BYE  or 


CTRL  BREAK 


CHD 
CHX 

I  ENTER  I  or  DIR 

r 

EDIT  or  E 
KILL 

LIST 

LOAD 

MEM 

PACK 

RENAME 

RUN 


Function 


Calls  the  shell  command  interpreter  to  execute 
an  OS-9  command. 

Returns  you  to  the  OS-9  system  or  to  the  pro^ 
gram  that  called  BASIC09. 

Changes  the  current  OS-9  data  directory. 

Changes  the  current  OS-9  execution  directory. 

Displays  the  name,  size,  and  variable  storage 
requirement  of  each  procedure  in  the 
workspace. 

Enters  the  procedure  editor-compiler  mode. 

Erases  one  or  more  procedures  from  the  work- 
space. 

Displays  a  formatted  listing  of  one  or  more 
poeedurea. 

Loads  all  procedures  from  a  disk  file  into  the 

workspace. 

Displays  in  bytes  the  current  workspace  size, 
or  reserves  a  specified  amount  of  mmiory  for 
the  workspace. 

Condenses  (compiles)  one  or  more  procedures. 

Changes  a  procedure's  name. 

Causes  a  procedure  in  the  workspace  to 
execute. 


SAVE 


Writes  one  or  more  procedures  to  disk. 
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Renaming  Procedures 

BASIC09's  RENAME  function  ig  important  for  two  reasons: 
First,  it  lets  you  load  into  the  workspace  procedures  that  have 
the  same  name.  After  you  rename  the  workspace  procedure  you 
can  load  the  second  file.  Second,  if  you  let  BASIC09  use  the 
default  procedttfe  saatiie,  "Program,"  you  can  rename  the  jffoce- 
dure  before  saving  it  to  disk.  By  doing  this,  you  avoid  writing 
over — and  destroying — an  existing  procedure  file. 

To  change  the  name  of  the  procedure  you  created  in  the  previous 
chapter  from  Program  to  Add,  type: 

rename  program  add  |  ENTER  1 


Listing  Procedure  Names 

You  can  use  the  DIR  command  to  see  if  RENAME  worked  prop- 
erly. DIE  displays  the  names  and  sizes  of  all  procedures  In  mem- 
ory. Because  programmers  use  this  command  frequently,  the 
system  recognizes  a  shorthand  call.  Instead  of  typing  d  i  r  |  enter  |, 
you  only  need  to  press  |  ENTER  |.  This  displays  a  table  of  the  Iffoce- 
dures  in  the  following  format: 

Name  Proe-Size  Data-Size 

♦add  182  32 

addl  217  42 

add2  218  42 

2198  free 

Proc-Size  refers  to  the  number  of  memory  bytes  refttired  for  the 
procedure.  Data -Size  refers  to  the  number  of  memory  bytes 
required  for  the  procedure's  variables  and  data  structures.  The 
asterisk  indicates  the  current  procedure.  System  commands  act 
on  the  current  procedure  unless  you  indicate  otherwise. 

The  last  line  of  the  DIR  display  tells  you  how  many  free  bytes  of 
mmaxef  iwiain  in  the  B^WQU  twofepW; 


Listing  Procedures 

You  can  use  the  LIST  command  to  view  procedure  lines.  To  dis- 
play the  current  procedure,  type: 

list  I  ENTER  I 


3-2 


The  ^stem  Mode  1 3 


Fbr  example,  this  is  the  listing  of  a  procedure  named  Alpha.bak: 
PRDCEDURf  ftlpha_bak 


0000 

DIM  A: STRING 

DIM  T: INTEGER 

000E 

000F 

PRINT  "Here  is  the  a 

bac  kwards  : " 

Iphabet 

0032 

PRINT 

0034 

FDR  T=90   ID  65  STEP 

-1 

004A 

PRINT  CHR$(T>; 

0051 

PRINT  " 

0057 

NEXT  T 

0062 

PRINT 

00G4 

PRINT 

006G 

END 

When  you  list  a  BASIC09  procedure,  the  system  precedes  each 
line  with  a  relative  storage  address.  The  relatiire  address  of  the 
first  procedure  line  is  always  0.  In  the  previous  example,  the 
beginning  address  of  the  second  procedure  line  in  the  workspace 
is  07  units  from  the  beginning.  The  beginning  address  of  the 
third  line  is  OE  hexadecimal  (14  decimal)  storage  units  from  the 
procedure  beginning. 

These  I-Code  addresses  provide  a  way  for  the  compiler  to  let  you 
know  where  it  finds  an  error  whsn  one  occurs. 

Because  BAS1C09  compiles  programs  into  I-Code,  it  must  disas- 
semble them  before  it  can  display  them  on  the  screen.  This 
means  that  the  lines  might  not  look  exactly  as  typed.  For 
instance,  BASIC09  converts  lowercase  keywords  (command 
names)  to  uppercase.  BASIC09  also  eliminates  some  spaces.  If 
your  program  uses  control  statements  such  as  IF/THEN,  FOR/ 
NEXT,  and  LOOP/ENDLOOP,  the  lines  in  these  decision  mak- 
ing or  looping  structures  are  indebted  as  shown  in  the 
Alpha.bak  example.  Regardless  of  the  appearance  of  your  listed 
procedures,  they  execute  correctly  if  yoU  type  their  commands 
correctly. 
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Listing  Procedures  to  a  File 

There  might  be  times  whm  WU  want  to  send  a  formatted  proce^ 
dure  listing,  including  I-Code  addresses,  directly  to  a  file.  Yoa 

can  do  this  using  OS-9's  redirection  symbol,  >.  To  save  the 
Alpha.bak  procedure  on  a  file  named  Alpha.list  in  the  current 
data  directory,  typer 

list  alpha.bak  >alpha.ll5t  |ENTER| 

If  you  have  several  procedures  in  the  workspace  and  want  to  list 
more  than  one  to  a  disk  file,  separate  the  procedure  names  with 
commas,  like  this: 

list  a  1 pha . one , a  1 pha . t wo , a  1 pha . t h r ee  >alpha.all 
I  ENTER  I 

In  both  of  the  preceding  cases,  the  system  creates  the  Alpha.list 
file  and  stores  the  specified  listings  in  it.  If  you  use  a  file  name 
tibst  ah%a%  exists,  B4^X300  dl^£g^  tli@  j^cm^l: 

Rewrite? : 

If  you  pB^s  (T),  Ihe  System  destec^ys  the  orli^fflal  file  «ad  over- 
writes it  with  the  new  listing.  If  you  press  {W\,  the  LIST  process 

terminates. 

If  you  wish  to  list  a  procedure,  or  group  of  procedures,  to  a  file 
that  is  not  in  the  current  data  directory,  be  sure  to  specify  the 
complete  pathlist,  such  as: 

list  alpha.bak   >  /d1  /programs/alpha  .  rev  [  ENTERl 

listing  Procedures  to  a  Printer 

In  the  same  manner  as  you  list  procedures  to  a  disk  file,  you  can 
list  one  or  more  procedures  to  your  printer.  Make  certain  your 
printer  is  connected  and  turned  on,  then  again  use  the  redirec- 
tion s3nnbol,  but  this  time  specify  the  printer  device,  like  this: 

list  alpha.bak  >/p  [ENTER I 

Or: 

list  alpha  .  one  .alpha  ,  two  .alpha,  three  >/p  [ENTERl 
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Using  a  Wildcard 

Using  the  OS-9  wildcard,  *,  you  can  list  all  procedures  in  the 
workspace.  For  instance,  if  the  procedures  Alpha.one,  Alpha.two, 
and  Alpha.three  exist,  list  them  to  the  screen  by  typing: 

list»  lEMTERl 

Send  the  list  to  a  file  by  typing: 

list*  alpha  ,  all  |  ENTER  | 

Or  send  the  list  to  your  printer  by  typing: 

li5t*  /p 

Note:  When  you  use  the  wildcard,  the  name  of  the  file  Ot 
devise  to  receive  the  listing  iiiime4iate]ly  follows  the  LIST* 
CEffiBmand..  Do  nest  Bts©  the  iiii»cfi«Ei  symbol. 

Saving  Procedures 

You  can  save  one  or  more  procedures  to  disk  using  the  SAVE 
command.  Unlike  LIST,  SAVE  does  not  include  relative 
addresses.  However,  the  syntaxes  for  the  SMM  wxd  hlWT'  iSm- 
mands  are  identical.  To  save  the  procedure  Alpha.bak  to  the  cur- 
rent data  directory,  type: 

save   alpha.bak    alpha.bak  |  ENTER  | 

If  Alpha.bak  is  the  current  procedure,  you  can  save  it  in  a  file 
named  Alpha.bak  by  tj^ing  save  |  enter  |. 

To  save  all  of  the  procedures  in  the  workspace  to  a  file  named 
AU.programs  in  the  eurrent  data  directory,  type: 

save*  All,  programs  fENTER  | 

As  with  LIST,  to  save  one  or  more  procedures  in  a  file  that  is 
not  in  the  current  data  directory,  make  sure  you  specify  a  com- 
plete pathlist. 

To  save  all  the  files  in  the  workspace  to  a  disk  file  with  the 
same  name  as  the  current  procedure,  type  save*  |  enter  |. 

If  the  disk  file  you  specify  does  not  exist,  BASIC09  creates  it.  If 
it  does  exist,  the  system  displays  the  prompt: 

Rewr  i  te? : 
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Press  [y]  to  write  over  the  oM  file  with  the  specified  file.  The  old 

file  is  destroyed. 

Press  (T]  to  terminate  the  SiW^E  operation. 

Loading  Procedures 

To  load  a  saved  procedure  back  into  BASIC09's  workspace,  use 
the  LOAD  command  and  specify  the  appropriate  pathlist.  For 
instance,  if  your  current  directory  is  still  the  directory  contain- 
ing Alpha.bak,  load  the  procedure  hy  typing: 

load  alpha.bak  I  ENTER  I 

To  load  Alpha.hak  firom  the  PROGRAMS  directory  on  Drive  fDl, 

type: 

load   /d1  /  programs/alpha. rev  |  ENTER  | 

You  can  run  and  edit  a  loaded  procedure  in  exactly  the  same 
manner  as  you  would  a  pocedure  you  created. 

Ifem  ^01  load  any  numbra'  of  procedures  into  the  "m/ek&pSL&s  as 
loag  as  your  computer  has  sufficient  memory.  However,  be  care- 
fill  that  you  do  not  load  a  procedure  with  the  same  name  as  a 
procedure  already  existing  in  the  workspace.  If  you  do,  the  new 
procedure  overwrites  (destroys)  the  original  procedure.  You  can 
rename  workspace  procedures  to  avoid  this  problem. 

Deleting  Procedures  from  the  Workspace 

You  can  clear  the  workspace  of  one  or  more  procedures  using  the 
KILL  command.  For  instance,  to  remove  Alpha.bak  from  the 
workspace,  type: 

kill  alpha  .bak  | ENTER! 

To  remove  more  tlutn  em  procedure  firom  the  workspace,  sepa- 
rate the  procedure  names  with  commas.  To  delete  Alpha.one  and 
Alpha.two,  type: 

k  ill  alpha:  .  one  .alpha .  two  |  ENTER  | 

%i  elmi  Ihe  eseiSixm  workspace,  regardless  <si  1^  number  ^  poce^ 
dures  it  cont«iB«,  use  the  BASIC09  wildcard,  *.  Type: 

kill*  I  ENTER  I 
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Changing  Directoriei 

You  change  working  directories  in  BASIC09  and  OS-9  in  the 
same  manner,  by  using  the  CHD  and  CHX  commands.  CHD 
changes  the  data  directory,  and  CHX  changes  the  ^cution 

directory. 

BASIC09  saves  files  in,  or  loads  files  firom,  the  data  directory, 
unless  you  specify  differently  in  the  command  pathlist.  It  stores 
packed  procedures  in,  or  loads  PACKed  procedures  from,  the  exe- 
cution directory,  unless  you  specify  differently  in  the  command's 
pathlist. 

Also,  if  you  want  to  access  OS-9  commands  from  BASIG09,  the 
system  first  looks  lor  the  c(»Eumands  in  memory.  If  they  are  not 
there,  it  looks  hr  thmi  in  the  @cecution  directory,  unless  you 
specify  differeaitly. 

If  your  data  directory  is  the  ROOT  directory,  and  you  wish  to 
change  to  a  directory  named  PROGRAMS  that  is  a  subdirectory 
of  the  ROOT  directory,  type  the  following  conunand  from  the 
command  mode  B :  pmpt 

phd  programs  |  ENTER  I 

If  your  current  execution  directory  is  the  system's  CMDS  direc- 
tory, and  you  want  to  change  to  a  CMDS  directory  in  the  sub- 
directory BASIC,  type: 

chx  basic/cmda  (ENTER | 

Whenever  you  change  to  a  directory  other  than  an  immediate 
subdirectory,  specify  a  complete  pathlist. 

Mmmting  OB-9  CommsmiM 

BASIC09  lets  you  use  OS-9  commands  at  any  time  from  the  sys- 
tem mode.  To  do  so,  precede  the  command  with  a  dollar  sign  ($). 
For  instance,  to  look  at  the  current  data  directory,  type: 

$dir  I  ENTER  | 

To  view  the  current  execution  directory,  type: 
$dir   X  I  ENTER  | 
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All  OS-9  commands  are  available,  and  you  &m  files,  format 
diskettes,  list  files,  or  use  any  other  functions  from  the  system 

mode.  The  only  restriction  is  that  your  computer  must  have 
enough  free  memory  to  handle  the  command  you  call.  If  you  find 
that  there  is  not  enough  memory,  try  using  the  IffiM  eittffiluQd 
to  reduce  reserved  memory.  Then,  try  the  command  again. 

Auto-Execute  Procedures 

The  BASIC09  compiler  makes  two  passes  through  the  procedures 
you  write.  When  you  enter  the  command,  the  compiler  performs 
an  initial  compilation,  checking  for  any  syntax  errors.  When  you 
leave  the  edit  mode,  the  system  eonipites  the  procedure  a  second 
time  and  checks  for  any  programming  errors.  With  the  PACK 
command,  you  can  further  compile  your  procedures  so  that  they 
are  smaller  and  eiiecute  even  faster. 

B/^CK  causes  an  extra  compiler  pass  that  removes  names,  line 
numbers,  and  non-executable  statements.  Before  packing  a 
procediir^  Im  mam  |m  save  it.  IMI^s  p>u  do  so,  you  can- 
not make  farther  changes  to  the  proeeAwam. 

Once  you  pack  a  file,  you  cannot  list  or  edit  the  packed  version. 
However,  if  you  save  the  procedure  to  disk  before  packing,  you 
can  still  list  and  edit  the  original  file,  then  pack  it  again. 

When  you  save  a  packed  procedure  on  disk,  BASIC09  does  not 
normally  store  it  in  the  data  directory.  Because  the  procedure  is 
now  executable,  the  system  st^es  il  in  Urn  mxmtA  msmlMn 
directory. 

Bbr  instance,  to  convert  Alpha.bak  to  a  packed  procedure  in  the 
execution  directory,  type: 

pack   a  Ipha  .  bak  |  ENTER  | 

If  you  want  to  save  a  packed  procedure  under  a  different  file- 
name, use  the  OS-9  redirection  symbol: 

pack  alpha.bak  >  backwards  | ENTER | 

After  packing  a  procedure,  you  can  delete  it  from  the  workspace. 
J£  ym  %hm  run  it,  BASIC09  automatically  loads  the  file  from 
and  ecKsasate  it. 

The  following  is  a  sequent^  commEUods  that  dtimQaistaib  pmsk* 
ing  and  executing  a  procedure  named  Alpha.bak: 
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pack  alpha. bak  [ EMTER |      packs  the  procedure  and  stores 

it  in  the  execution  directory. 

kill  alpha. bak  I  ENTER  |      deletes  the  procedure  from  the 

workspace. 

ran  alpha. bak  [ ENTER |        loads  the  file  into  memory 

outside  the  workspace  and 
essecutes  it. 

kill  a  1  pha .  ba  k  |  ENTER  |     deletes  the  ittodule  from 

memory 

Yaa  do  not  need  to  kill  the  file  immediately  after  execution,  but 
until  you  do,  the  file  reduces  available  memory. 
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Chapter  4 


The  Edit  Mode 


You  briefly  used  the  BASIC09  built-in  editor  to  create  the  Add 
prcieieiuafe  ixt  Obuapter  2.  la  aiiditiQiL  to  tTm  fbititreg  fm  JmmsA 
th^e,  the  editor  has  oth^  importaist;  fiutsMons. 

Although  you  can  use  any  text  editor  or  word  processor  to  write 
BASIC09  procedures,  the  BASIC09  editor  offers  two  handy 
features: 

•  It  is  both  string  and  line  number  oriented.  You  can 
search  for  strings  of  characters,  and  replace  them,  and 
you  can  reference  text  with  optional  line  numbers. 

•  It  interfaces  with  the  compiler  and  decompiler.  This  fea- 
ture lets  BASIC09  check  continuously  for  syntax  errors 
and  enables  you  to  use  procediures  that  conserve  memory. 

Edit  Commands 

The  fellowtog  is  a  suxamaif^  of  the  edit  commands: 


Conmiand  Ftmclion  

I  ENTER  I  Moves  the  edit  pointer  to  -^e  next  line.  Causes 

a  comnuind  to  execute. 

+nmnb&  Moves  the  edit  pointer  ahead  mmber  lines. 

+*  Moves  the  edit  pointer  to  the  last  line. 

-nwnber  Moves  the  edit  pointer  back  number  lines. 

-*  Moves  the  edit  pointer  to  the  first  line. 

text  Inserts  an  unnumbered  text  line  before  the 

current  line. 

ntext  Inserts  the  line  numbered  n  in  its  correct 

ntunne  position. 

n  Moves  the  edit  pointer  to  the  line  nomb^ed  n. 

cl8trl/str2/        Changes  the  next  occurr^ice  of  strl  to  sfrS. 


4-1 


BASIC09  Reference 


Command  Function 

c*/strl/str2/  Changes  all  oeeifflTences  of  strl  to  str2. 

d  Deletes  the  current  line. 

d*  Deletes  all  the  lines  in  the  procedure. 

1  Lists  the  current  procedure  line. 

1*  Lists  all  the  procedure  lines. 

q  Terminates  the  edit  session. 

r  Renumbers  lines  beginning  at  the  current  line 

in  increments  of  10. 

r*  Renumbers  all  lines  in  increments  of  10. 

r  B  HeimmbM  lines  beginning  at  Line  n  in 

incremetits  of  10. 

r  jhI  n2  Renumbers  lines  beginning  at  Line  nl  in 

increments  of  n2. 

s  /string/  Searches  for  the  first  occurrence  of  string. 

s*  /string/  Searches  for  all  occurrences  of  string. 


Using  the  Editor 

The  easiest  way  to  understand  the  edit  commands  is  to  use 
them.  The  following  sections  show  you  the  functions  of  BASIO09 

edit  mode. 

The  manual  uses  line  numbers  in  the  following  procedure  to 
acquaint  you  with  all  the  functions  of  the  editor.  Remember, 
however,  line  numbers  are  not  required  with  BASIC09.  Proce- 
dures and  programs  without  line  numbers  are  shorter,  faster, 
and  eaaier  to  read. 

First,  you  need  a  procedure  with  which  to  work.  Rjsition  your- 
self in  the  system  mode.  Then,  type  this  line: 

e   prose  |  ENTER  | 
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Now,  type  the  following.  (Remember,  the  small  rectangle  repre- 
sents a  space.) 

0100  DIM  PHRftSESC30):STR:rN© 

□120  FDR  T=1    TQ  30 

D130  READ  PHRASESCt) 

0140  NEXT  T 

□160  PRINT 

□170  FIRST=RND(10) 

□180  SECDND=RND(9)+1 1 

□190  THIRD=RND(9)+21 

0200  PRINT  PHRASESfFIRST) ; 

0210  PRINT  PHRASESCSECDND) ; 

□220  PRINT  PHRASESCTH I RD) ; 

□240  PRINT 

□300  DATA  "Lovea","An  orangeD", 

0310  DATA  "ft  dark  cloudD"j"A  goose  featherO", 
"A  PopsicleO" 

0320  DATA  "Home  cook IngO"  ,  "Co  1 d  piZzaO", 
"Rock  Ti'  RollQ" 

0330  DATA  "is  charming  1  i k eZ" , "ma k es  me  dream  ofQ" 
1340  DATA  "is  as   sticky  asQ","eaTi  ooze 
likeO", "smells  likeO" 

0310  DftTA  "cffTi  be  as  tough  to  forget  asO","can 

hurt  like"" 

□3G0  DATA  "can  be  as  cynical  as^", "makes  a  mockery 
ofD" 

0370  DATA  "drives  me  as  crazy  asQ" 

0380  DATA  "a  sticky  1 o 1 1 i pop . " , "a  web  of 

intrigue." 

□390   DATA  "castor   oil.", "a   chocolate   bath.", "a 
broken  toe." 

□400  DATA  "honey  and  things .", "personal 
defeat . " , "a  Wet  diaper . " 

□410  DATA  "strange  happen i ngs .", "a  pennyless 

purse." 

When  you  finish  typing  the  procedure,  type  q  |  enter  |  to  return  to 
the  system  mode.  Now  you  can  test  the  program  by  typing 
either: 

run  I  ENTER  | 

or 

run  prose  |  ENTER  | 
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After  trying  the  procedure,  return  to  the  edit  mode  by  typing  e 

I  ENTER  |. 

After  displaying  the  procedure's  name,  the  editor  displays  Line 
100  preceded  by  an  asterisk.  The  asterisk  lets  you  know  which 
Hne  is  the  current  line  (or  the  line  at  which  the  edit  pointer  is 
bcated). 

Smrehing  Through  a  Procedure 

You  can  examine  a  |a-Q@@dttre  in  three  ways: 

•  Press  I  ENTER  I  to  display  the  procedure  one  line  at  a  time. 

•  Skip  through  the  procedure  to  a  particular  line. 

•  List  part  or  all  of  the  procedure  to  the  screen. 

When  you  use  either  of  the  first  two  methods,  the  line  you  select 
to  display  becomes  your  current  line.  When  you  use  the  third 
method,  the  current  line  does  not  change. 

Using  I  ENTER  I 

If  you  are  still  positioned  at  Line  100,  but  want  to  examine  the 
first  line  of  data,  Line  300,  press  |  enter  |  12  times  to  move  down. 

Using  the  Plus  Sign  to  Move  Forward 

Another  method  of  moving  to  a  specific  line  is  to  type  a  plus 
sign  followed  by  the  number  of  lines  you  need  to  advance  to  get 
there.  Positioned  at  Line  100,  you  can  type: 

+  12  I  EMTER  I 

Whether  you  press  |  enter  |  or  use  the  plus  slga,  the  last  line  dis- 
played is  now  your  eurrrait  line. 
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Accessing  a  Line  Using  the  Line  Number 

The  third  way  to  move  to  a  particular  line  is  to  type  the  line 
number,  followed  by  |  enter  |.  For  instance,  to  jump  back  to  Line 
100,  type: 

1  00  I  ENTER  I 

The  editor  displays  Line  100  and  makes  it  your  current  line. 

Using  the  Minus  Sign  to  Move  Backward 

In  the  same  manner  that  you  move  forward  in  the  procedure 
using  the  plus  sign,  you  can  move  backward  using  the  minus 
sign,  or  hyiA,en. 

Type  3  0  0  I  ENTER  I  to  return  to  Line  300.  To  display  Line  240  and 
make  it  your  current  line,  type: 

-  I  ENTER  I 

To  display  Line  190  and  make  it  your  current  line,  type: 

-4  I  ENTER  I 

Tim  ^obal  Symbol 

The  BASKJOt  editor  also  makes  use  of  the  asterisk  as  a  global 
symbol.  For  instance,  following  a  command  with  an  asterisk 
causes  that  command  to  affect  the  entire  procedure. 

This  feature  lets  you  move  quickly  to  the  beginning  and  end  of 
the  procedure.  To  return  to  Line  100,  the  first  line,  type: 

-«  I  ENTER  I 

To  move  to  the  end  of  the  procedure,  past  all  the  numbered  lines, 
type: 

+  *  I  ENTER  I 
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Using  LIST 


The  LIST  command  lets  you  select  one  or  more  lines  for  display 
on  yoar  sa^en.  To  see  this,  make  the  first  line  your  current  fine, 
then  tjipe: 


To  list  one  or  more  lines,  type  the  LIST  command  followed  by  the 
number  of  lines  you  want  displayed.  For  instance,  typing  15 
I  ENTER  I  causes  the  current  line  and  four  others  to  appear  on  the 
screen,  as  shown  in  the  following  sequence  of  commands  and  the 

-•  I  ENTER  I 

1  5  I  ENTER  I 

PROCEDURE  Prose 

100  DIM  PHRASES(30):  STRING 

laa  FOR  T=1  TO  30 

130REfiD  PHRftSrSCT) 

140   NEXT  T 
160  PRINT 

You  can  also  use  LIST  with  the  BASIC09  global  symbol,  *.  Typ- 
ing an  asterisk  after  the  LIST  command  produces  a  listii^  of 
the  entire  procedure. 

Deleting  Lines 

Earlier,  the  manual  showed  that  you  can  delete  the  current  line 
by  typing  d  [  enter  |.  Because  this  is  such  a  simple  process,  be 
sure  you  don't  do  it  by  accident.  Removing  the  wrong  line,  or  too 


Ysa  can  also  remove  a  group  of  lines  from  a  procedure  fay  tjrping 

d,  followed  by  the  number  of  lines  you  want  to  delete.  This  com- 
mand deletes  the  current  line  and  specified  following  lines. 
Again,  be  careful. 

"You  can  remove  all  of  the  lines  in  a  procedure  by  using  the 
global  symbol,  *.  Typing  d»  I  enter  |  erases  all  procedxire  text. 
Bmevtgr,  Ihe  procedure  name  still  resite  M  the  •wortepaee.  lb 
delete  an  entire  procedure,  including  the  name,  use  the  KILL 
command  firom  the  system  mode. 


1  I  ENTER  1 
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If  you  decide  you  don't  like  the  rmms  used  in  the  DATA  lines  of 
the  Prose  procedure,  erase  all  of  this  DATA  lines  containing 
nouns  (Lines  300-320)  and  replace  them.  To  do  so,  make  Line 
300  your  current  line  by  typing: 

300  I  ENTER  I 
Then  type: 

d  i  ENTER  I 

Line  300  disappears  and  Line  310  takes  its  place  as  the  current 
line. 

An  alternate  method  of  deleting  the  DATA  lines  uses  only  one 
command.  To  delete  Lines  300  through  410,  follow  the  DELETE 
command  with  the  number  of  lines  you  want  to  remove — ^in  this 
casej  three: 

ci3  [  ENTER  I 

Lines  300,  310,  and  320  disappear.  Line  330  becomes  the  cur- 
rent line.  Move  back  a  line  to  check  that  the  deletions  worked. 
The  line  numbers  now  skip  from  240  to  330. 

Now,  you  need  new  nouns  for  the  procedure.  Type  them  in  the 
same  style  as  the  old  lines,  such  as: 

□300  DATA  "A  TelephoneQ,"A  tickleO", 
"A   girlD","A  boyD" 

D315  DATA  "Bad   1  ac  IcQ"  ,  "MoneyQ"  ,  "A  bad  betD", 
"A  lumpy  bqdD" 

DIM  DATA  "A  deep  t houghtO" , "Sunl i ghtO" 

Save  a  copy  of  your  procedure  to  disk  by  exiting  the  editor  and 
using  the  SAVE  command.  Then  return  to  the  edit  mode  and  try 

the  global  delete  by  typing: 

d»  I  ENTER  I 

Changing  Text 

Using  CHANGE  tells  the  editor  to  search  for  existing  text  and 
replace  it  with  new  text.  CHANGE,  like  DELETE,  can  easily 
cause  unwanted  resvilts  if  you  are  not  careful. 
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The  CHANGE  commEind  requires  that  you  use  delimiters  to  sep- 
arate the  command  from  the  search  t^t,  and  to  separate  the 
search  text  from  the  new  text.  You  can  select  any  of  the  following 
characters  for  a  delimiter,  as  long  as  it  does  not  appear  in  either 
the  search  text  or  the  new  text: 

!#%"&()-+  ={}[]■'  "<>,.?/  \  I 

Do  not  use  the  global  symbol  (*)  for  search  and  replace  opera- 
tions. This  manual  uses  a  slash  (/)  as  the  CHANGE  delimiter. 

The  following  steps  outline  the  correct  use  of  CHANGE: 

1.  Position  the  editor  either  before  or  on  the  line  in  which 
you  want  to  make  a  change. 

2.  Type  c  (for  CHANGE).  Do  not  use  a  preceding  space. 

3.  Type  a  delimiter  character,  such  as  /. 

4.  Type  the  characters  to  be  changed,  following  them  with 
the  delimiter. 

'§i  Type  the  new  text,  followed  by  the  delimiter. 

5.  Press  [  ENTER  I. 

Note:  It  is  a  good  idea  to  turn  on  OS-9's  upper-  and  lower- 
case function  before  attempting  change  or  search  opera- 
tions. If  you  do  not,  pau  cannot  tell  whether  the  text  you 
want  to  find  is  upper-  or  lowercase,  or  some  combination  of 
the  two.  If  you  type  the  wrong  case,  the  change  or  search 
foils. 

In  case  you  didn't  notice  when  typing  the  procedure,  Line  410 
contains  an  incorrectly  spelled  word,  pennyless.  To  correct  this 
error,  type  the  following: 

o/pennyless/peTiniless/  |  ENTER  | 

Immediately,  the  editor  displays  Line  410,  with  pennyless 
changed  to  penniless. 

Suppose  you  decide  to  change  the  number  of  sentence  combina- 
tions available  in  Prose.  The  procedure  now  has  30  data  entries. 

If  you  add  five  subjects,  five  verb  phrases,  and  five  objects,  the 
procedure  also  needs  other  changes  (for  instance,  the  DIM  state- 
xomt  in  Line  100,  the  loop  size  in  Line  120,  and  the  RND  state- 
ments in  Lines  170  through  190). 
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A  quick  way  to  change  the  number  30  in  Lines  100  and  120  is 
to  use  change's  global  function.  To  change  all  occurrences  <£ 
30  to  45,  position  the  editor  at  Line  100,  and  type: 

o»/30  /45/  I  ENTER  I 

Use  the  CHANGE  and  global  CHANGE  functions  to  adjust  the 
RND  statement  values  in  Lines  170,  180,  and  190. 

As  well  as  making  chginges,  you  can  use  the  CHANGE  command 
to  quickly  delete  portions  of  test  within  a  line,  lb  do  this,  type 
delimiters  without  mm  text,  in  this  fe^ion: 

c/Dfeather//  |  ENTER  | 

This  command  changes  the  text  A  goose  feather  in  Line  210 

to  A  goose. 

Searching  for  Text 

The  editor's  SEARCH  command,  S,  works  in  the  same  manner 
as  the  CHANGE  command.  However,  SEARCH  only  requires 
you  to  specify  a  block  of  text  to  find. 

With  SEARCH,  you  use  delimiters  to  enclose  the  text  to  find.  To 
test  the  function,  position  the  editor  at  the  beginning  of  t^  tjy 
typing: 

[  ENTER  I 

Now,  search  for  the  word  phrases,  by  typing: 

s/phrases/  |  ENTER  | 

The  screen  displays: 

♦0000    100   DIM  phra5es(30):STRING 

To  find  all  occurrences  of  phrases  throughout  the  procedure,  use 
the  global  s3mboh  Tj^e: 

s»/phrase5/  lEWTER:! 
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Renumbering  Lines 

The  RENUMBER  command,  i,  reorders  all  numbered  lines  and 
all  referesttcies  to  mimb^ed  lines.  Tm  can  0ve  RKNtMBER 

either  one  or  two  parameters.  The  first  is  the  beginning  line 
number.  The  second  is  the  increment  you  want.  The  default 
increment  is  10. 

For  instance,  the  Pr(Bi  pOcedure  line  numbers  skip  from  Line 
100  to  Line  120.  You  can  renumber  the  entire  procedure  by  mov- 
ing the  editor  to  Line  100,  and  then  typing: 

r  1  0  I  ENTER  | 

To  change  the  numbering  to  increments  of  5,  beginning  at  Line 
100,  type: 

r  10  0,5  I  ENTER  I 

Yon  can  also  change  line  numbering  in  portions  of  the  procedure. 
To  do  this  move  the  editor  to  the  line  where  you  want  the  new 
numbering  to  begin.  Then,  type  in  tte  new  parameters.  To 
renumber  Line  100  as  Line  200  and  continue  with  increments  of 
10,  position  the  editor  at  Line  100.  Then,  type: 

r   200,1  0  I  ENTER  | 

If  you  are  not  positioned  at  the  first  line  of  a  procedure,  but  you 
wish  to  renumber  all  lines,  you  can  use  the  global  symbol  to  do 
the  job.  From  anywhere  in  the  procedure,  type: 

r*    100,10  I  ENTER  I 

This  renumbers  the  entire  procedure  in  increments  of  10. 
Adding  Lines 

There  mm.  tsro^  Wi^-s  te  mM  mm  lines  to-  n  prQewfa^,.  %u  mm 

•  Position  the  editor  one  line  below  the  position  for  the  new 
line.  Then,  type  the  new  line  and  press  |  enter  |.  When 
inserting  lines  without  numbers,  be  sure  to  type  a  space 
as  the  first  character  ot  ihs  line  to  tell  the  editor  that 
the  following  text  is  a  new  procedure  line. 

•  Type  a  new  line,  giving  it  a  line  number  that  falls 
between  two  existing  line  numbers. 
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The  following  procedure  adds  more  choices  to  the  Prose  program. 
It  also  adds  a  feature  that  lets  you  press  |  enter  |  for  additional 
output,  rather  than  having  to  rerun  the  procedure.  Use  the 
information  presented  in  this  section  to  help  you  insert  the  new 
lines  ixtio  yaai  |3f ogFaxet.  Because  fon  vm^  ekanp  scmm  lines, 
as  well  as  add  lines,  the  following  listing  includes  the  entire 
procedure. 

Referring  to  the  original  Prose  listing,  the  lines  to  change  are: 
100, 120, 170, 180,  and  190. 

The  lines  to  add  are:  110,  150,  230,  250,  260,  270,  305,  325, 
372,  374,  376,  420,  430. 

PRDCEPURE  pro5e2 

1B0  DIM  PHRftSES(4i3!STRING 

110  DIM  RESPONSEiSTRING 
120  FOR  T=1   TD  45 

im  mm  PHRASEsct) 

140  NEXT  T 
150  REPEAT 

1G0  PRINT 

170  FIRST=RNDC15) 

1  8  0  SE  CO  HD  ^  RND  C 1 4  >  + 1 6 

190   THIRD  =  RND(1  4)-<-31 

200   PRINT  PHRASES(FIRST); 

210   PRINT  PHRASESCSECOND) ; 

220  PRINT  PHRASES(THIRD) ; 

230  PRINT 

240  PRINT 

250   PRINT  "[TjZrZIIDPress   ENTER  for  another 
witticism. . ." 

260  INPUT  "rrrrrrm-nOr  press  the  spacebar  and  press 
ENTER  to  end  ..." , RESPONSE 

270   UNTIL  RESPONSE)"" 

30  0   DATA   "LoveZ","An  o  ra  ngeZ,"  ,  "Hums  n  i  t  yD"  , 
"A  kissD" 

305  DATA  "A  cGinpiitepD" /'A  bookn","Miseryn" 
310  DATA  "A  dark  cloudn","A  goose  featherO", 

"A  PopsicleD" 

320   DATA  "Home  c oo k i ngu" , "Co  1 d  pizzaQ", 
"Rock  n'  RollD" 

325  DATA  "Snow  in  4tfiTen","A  |laaa  houaeO" 

330  DATA  "is  charming  likeD","makeH  me  dream  ofD" 
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340  mTfii  "Is  as  sticky  a5a","can  ooze  likeD", 
"smells  likeD" 

350  DATA  "can  be  as  tough  to  forget  asD", 
"can  hurt  likeD" 

360  DATA  "can  be  as  eynleBl  asD", 

"makes  a  mockery  ofD" 

370   DATA  "drives  me  as   crazy  asD" 

372  DATA  "can  bother  me  1 i keD" , "blac kens  my  hopes 
1  i  k  eD" 

374  Bfttfi  "can  ttcklfe  me  1  i keO*' , "eaa  lie  as  funny 
asD" 

37G  DATA  "has   the  effect  ofD" 

380  DATA  "a  sticky  lo 1 lypop . " , "a  web  of 

intrigue . " 

390  DATA  "castor  oil.", "a  chocolate  bath.", "a 
broken  toe." 

400  DATA  "honey  and  t h i ngs  .  " , "per sona 1 
dsf'SM  t . "        #8:4  d  l.a  p  e  r  . " 

410  DITPI  "strange  happenings "a  penniless 
purse." 

420  DATA   "a   slimy  snake.", "a  bad  habit." 

430  DATA  "a  bad  memory  chip.", "a  good  fight.", "a 

silly  friend ." 

The  Next  Step 

Even  the  best  programmers  make  mistakes — a  lot  of  them. 
BASIC09  provides  a  way  to  catch  programming  mistakes  quickly 
and  correct  them.  The  next  chapter  tells  you  about  BASICOS's 
powerful  debugging  functions. 


4-12 


Chapter  5 


The  Debug  Mode 


The  term  debug  refers  to  the  process  of  finding  programming 
errors  and  correcting  them.  BASIC09's  debugging  features 
include  symbolic  debugging  capabilities  that  let  you  examine 
variable  values  and  test  and  manipulate  procedures. 

With  Debug,  you  can: 

•  Examine  and  change  variables. 

•  Trace  procedure  execution.  Debug  lets  you  execute  proce- 
dures and  vrntch  them  run  in  slow  motion. 

•  Pause  procedure  ^cution. 

•  Resume  procedure  execution. 

•  Set  procedure  breakpoints  that  automatically  switGh  to 

the  debug  mode. 

•  Select  the  use  of  degrees  or  radians  for  trigonometric 
functions. 

•  Pra-form  calculations. 

•  Call  OS-9  system  commands. 

Entering  the  Debug  Mode 

You  enter  Debug* 

•  Automatically,  whenever  an  error  occurs  during  the  exe- 
cution of  a  procedure  (unless  you  have  included  an  ON 
ERROR  GOTO  statement  to  handle  the  error). 

•  Automatically,  when  a  procedure  executes  a  PAUSE 

statement, 

•  When  you  press  I  Ctrl  \[c]  during  the  execution  of  a 
procedure. 

You  can  tell  when  BASICOB  enters  the  Debug  mode  by  the 

appearance  of  the  D :  prompt.  When  you  see  D : ,  Mlowed  by  the 
cursor.  Debug  is  waiting  for  your  command. 

The  following  is  a  reference  of  all  the  Debug  commands  and  what 
they  accomplish: 
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Command 


Function 


BREAK 


CONT 


DEG/RAD 


Calls  0&«9's  command  shell  interpreter  to  run 
a  program  or  an  OS-9  command.  From  the 
Debug  prompt,  tj^e  $ ,  followed  by  the  name  of 
the  program  or  command  you  want  to  execute. 


Example:  $li5t   procedur  e_o  n  e  |  ENTER  | 


Sets  a  breakpoint  immediately  before  the  ^ec- 
ified  procedure.  Use  cfwnand  t0  fe-^ter 
Debug  when  me  procedure  calls  another. 

If  you  have  three  procedures  that  call  each 
other — Procl,  Proc2,  and  Proc3 — and  Proc3 
does  not  seem  to  pass  the  correct  values  to 
Proc2  when  it  retumsj  set  a  breakpoint  at 
Procf.  This  causes  BASIC09  to  enter  Debug 
before  re-entering  Proc2.  "Sou  can  then  check 
your  variable  values. 

You  can  use  one  breakpoint  for  each  active  pro- 
cedure. Debi^  r^oves  breakpoints  immedi- 
a.tely  after  encountering  them. 

A  procedure  must  run  before  you  can  set  a 
breakpoint  in  it.  Use  BREAK  to  stop  execution 
when  a  called  procedure  returns  to  a  proce- 
dure previously  executed. 


Example:  BREAK  proc2  |  enter  I 


Causes  procedure  execution  to  continue. 
Example:  cont  |  enter  | 

Selects  either  degrees  or  radians  as  the  unit  of 
raeasureoliMll  It  MfiBcttieMB  teeteffis.  DEG 
and  RAD  afi^  mlf  #ie  current  iH-ocedure. 


Examples:  deg  |  enter  | 

red  I  ENTER  I 
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DIR  Displays  the  name,  size,  and  variable  storage 

requirements  of  each  procedure  in  the  work- 
space. The  current  working  procedure  has  an 
asterisk  before  its  name.  All  packed  proce- 
dures have  a  dash  before  their  aames.  DIR 
also  shows  the  available  memory  in  the 
workspace. 

If  you  provide  a  pathlist,  DIR  sends  its  data  to 
the  specified  file. 

Example:  dir  |  enter  | 

d  i  r   procedures  |  ENTER  | 

Q  Terminates  execution  of  the  procedure,  closes 

any  apm  paths,  and  exits  to  the  System  mode. 

Example:  q  iffffiBI 

LET  Assigns  a  new  value  to  a  variable.  You  must 

specify  variable  names  that  are  already  ini- 
tialized by  your  program.  In  the  Debug  mode, 
you  cannot  use  LET  to  copy  one  array  to 
another  array  as  you  can  in  BASIC 
procedures. 

Example:  let  a       0  | enter | 

let  fruit   :»  "oranfes'*  |EWTEH| 

LIST  Displays  a  source  listing  of  the  suspended  pro- 

cedure. The  display  is  formatted  and  includes 
I -code  addresses.  An  asterisk  appears  to  the 
left  of  the  last  executed  statement. 

Example:  list  |  enter  | 

PRINT  Displays  the  values  of  variables  used  in  the 

suspended  procedure.  You  cannot  introduce 

new  variable  names  in  the  Debug  mode,  and 
you  cannot  display  array  structures. 

Example:  print  fruit  I  enter  I 

STATE  Lists  the  nesting  order  of  active  procedures. 

STATE  displays  the  highest-level  procedure  at 
the  bottom  of  the  calling  list.  The  lowest-level 
procedure  is  the  suspended  procedure. 


Example:  state  |  enter  | 
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STEP  Causes  ^i^cution  of  the  su^^ided  procedure 

in  specified  mcrements.  Ibr  example,  typing 
STEP  5  I  ENTER  |  executes  the  equivalent  of  the 
next  five  statements.  If  you  enter  STEP  with- 
out an  increment  value,  the  step  rate  is  1. 

Using  STEP  with  the  trace  function  lets  you 
obsrarve  the  source  lines  as  they  execute. 

Because  compiled  I-code  contains  actual  state- 
ment memory  addresses,  the  top  or  bottom 
statements  of  loop  structures  execute  only 
once.  For  example,  in  FOR/NEXT  loops,  FOR 
executes  once,  and  the  statement  following 
FOR  appears  to  be  the  top  of  the  bof  ; 

TRON/TROFF  Turns  on  or  turns  off  the  trace  function.  Trace 
on  (TRON)  causes  the  system  to  reconstruct 
the  compiled  code  of  each  statement  line  into 
source  code.  Debug  displays  the  source  code 
before  the  statement  is  executed.  "It  the  state- 
ment causes  the  evaluation  of  one  or  more 
expressions.  Debug  displays  each  result  follow- 
ing the  statement.  The  result  is  preceded  hy 
an  equal  sign. 

The  trace  function  is  local  to  the  current  |n:o- 
cedure.  If  the  suspended  procedure  calls 
another  procedure,  Debug  suspends  the  trace 
function  until  control  returns  to  the  original 
procedm-e.  However,  once  you  turn  on  trace  for 
a  procedure,  it  continues  in  effect  until  you 
turn  it  off.  This  means  that  if  you  turn  trace 
on  in  a  called  procedure,  and  another  proce- 
dure subsequently  calls  it,  trace  continues  to 
display  the  called  procedtire's  opea'ations. 

Examples  t  roTi  1  enter  | 

trof  f  I  ENTER  I 

When  Things  Go  Wrong 

Programming  errors  show  up  in  two  ways.  Either  your  procedure 
produces  incorrect  results,  or  it  terminates  p-ematurely. 
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In  the  first  instance,  you  can  stop  your  procedure  and  enter 

Debug  by  pressing  |  CTRL  IfT], 

However,  sometimes  your  program  executes  too  quickly  to  allow 
you  to  stop  it  at  the  appropriate  place.  In  this  case,  you  can  use 
the  Edit  mode  to  insert  a  PAUSE  command  where  you  wish  the 
^amSmet  im  stiq).  MOSE  eauses  the  procedure  to  Imlt  execution 
BxA  eE&mc  the  Debug  mode. 

Once  in  Debug,  you  can  use  the  PRINT  command  to  examine 
the  procedure  variables.  You  can  use  LET  to  manipulate  the 
variable  values  to  determine  where  the  error  or  errors  occur.  Per- 
haps you  forgot  to  initialize  a  variable  or  forgot  to  increase  a  loop 
counts. 

Using  the  Trace  Function 

Sometimes,  errors  are  more  difficult  to  discover.  If  so,  the  next 
step  is  to  use  the  trace  function.  To  do  this,  type: 

t  ron  I  ENTER  | 

Now  press  [  enter  |.  Each  time  you  press  |  enter  |,  Debug  executes 
one  line  of  the  procedure.  You  can  see  the  original  source  state- 
ment, and  if  an  expression  is  evaluated,  Debug  prints  the  result 
of  the  ^pressum,  preceded  by  an  equal  sigiL 

In  this  manner,  you  can  step  through  the  entire  procedure,  or 
any  part  of  it,  Kcamining  variable  values  as  you  go. 

What  About  Loops? 

The  STEP  command  is  helpful  if  you  find  yourself  tracing  the 
operation  of  a  loop.  Once  you  determine  that  the  loop  works  cor- 
rectly, you  can  avoid  tedious,  step-by-step  repetitions  by  turning 
trace  off  and  using  STEP  to  quickly  rim  fhrmgh  the  ItM^.  Hien, 
turn  trace  back  on  and  resume  single-step  debugging.  For 
instance,  type: 

troff  I  ENTER  | 
step   200  I  ENTER  I 
Iron  I  ENTER  | 
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In  Multiple  Procedures 

Although  the  trace  function  is  local  to  a  procedure,  you  can 
pause  and  turn  on  the  trace  function  in  as  many  procedures  as 
you  wish.  Trace  continues  to  operate  in  eaeh  p-ocedure  lintil  you 
turn  it  off  using  TROFF. 

To  cause  a  procedure  to  halt  execution  when  it  is  called  by 
another  procedure,  use  the  BREAK  ccanmand. 
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Data  and  Variables 


Data  Types 

Data  is  information  on  which  a  computer  performs  its  operations. 
Data  is  always  numeric  but,  depending  on  your  computer  appli- 
cation, it  can  represent  values,  symbols,  or  alphabetic  characters. 
This  means  that  the  same  items  of  physical  data  can  have  very 
di£telQi  kgkxd  aaeanings,  depending  cm  how  a  program  intw- 
prets  it. 

Fbr  instance,  65  can  represent: 

•  A  numeric  value  to  be  used  in  a  calculation. 

•  The  location  of  a  memory  address. 

•  Tim  offset  of  a  memory  location. 

•  The  two  character  syn^ls  6  and 

•  The  character  A  in  the  ASCII  table.  ASCII  is  the  abbre- 
viation for  the  American  Standard  Code  for  Information 
Intercheinge. 

Because  (rf  the  differences  in  how  BASIC09  uses  data,  the  sys- 
tem lets  you  define  five  types  of  data.  For  instance,  there  are 
three  ways  to  represent  numbers.  Each  has  its  own  advantages 
and  disadvantages.  The  decision  to  use  one  way  or  another 
depends  on  the  specific  program  you  are  developing.  The  five 
BASIC09  data  types  are  byte,  integer,  real,  string,  and  Boolean. 

in  addition  to  the  preceding  data  types,  there  are  complex  data 
types  you  can  define.  The  manual  discusses  complex  data  struc- 
tures at  the  end  of  this  chapter. 

The  byte,  integer,  and  real  data  types  represent  numbers. 

The  string  data  type  represents  character  data  (alphabet,  punc- 
tuation, numeric  characters,  and  other  symbols).  The  default 
length  of  strings  is  32  characters.  Using  the  DIM  statement,  you 
can  specify  strings  of  both  longer  and  ^rter  lengths. 

The  Boolean  data  type  represents  the  logical  value,  TRUE  or 
FALSE. 
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You  can  create  arrays  (lists)  of  any  of  these  data  types  with  one, 
two,  or  three  dimensions.  The  following  table  shows  the  data 
types  and  their  characteristics: 


lype 

Allowable  Values 

Memory 
Requirements 

BYTE 

Whole  numbers  (0  to  255) 

One  byte 

INTEGER 

Whole  numbers  (-32768 
to  32767) 

Two  bytes 

REAL 

Floating  point 
(±1*10»=38) 

Five  bytes 

STRING 

Letters,  digits, 
punctuation 

One  byte  per 
character 

BOOLEAN 

True  or  false 

Real  numbers  appear  to  be  the  most  versatile.  They  have  the 

greatest  range  and  are  floating  point.  However,  arithmetic  opera- 
tions involving  real  numbers  execute  much  more  slowly  than 
those  involving  integ^  or  tiyfei  values.  Real  numbers  also  take 
up  considerably  more  xamaoy  storage  Space  than  the  other  two 
numeric  data  types. 

Arithmetic  involving  byte  values  is  not  appreciably  faster  than 
arithmetic  involving  integers,  but  byte  data  conserves  memory. 

If  you  do  not  specify  the  type  of  variable  (a  symbolic  name 
for  a  value)  in  a  DIM  statement,  BASIC09  assumes  the  vari- 
able is  real. 

The  Byte  Data  Type 

Byte  variables  hold  unsigned  eight-bit  data  (integers  in  the 
range  0  through  255).  Using  byte  values  in  computations, 
BASIC09  converts  the  hyte  values  to  16-bit  integer  values.  If  you 
store  an  integer  valae  that  is  too  large  for  the  byte  range, 
BAH[dOS  stor^  only  the  least-significant  eight  bits  (a  value 
255  or  less),  and  does  not  return  an  error. 


6-2 


Data  and  Variables  I  6 


The  Integer  Data  Type 

Integer  variables  require  two  bytes  (16  bits)  of  storage.  They  can 
fall  in  the  range  -32768  to  32767.  If  a  caltsolatmn  involves  both 
integer  values  and  real  values,  BASIC09  presents  the  result  of 
the  calculation  as  a  real  number. 

Yau  can  also  use  hexadecimal  values  in  integer  data.  To  do  so, 
precede  the  value  with  the  dollar  sign  ($).  For  instance,  to  repre- 
sent the  decimal  value  199  as  hexadecimal,  type  $C7.  The  hexa- 
decimal value  rar^  is  $0000  throuf  h  $f  FFP. 

IS  foil  give  an  integer  variable  a  valtie  that  is  outside  the  integer 
range  (greater  than  32767  or  less  than  -32768),  BASIC09  does 
not  produce  an  error.  Instead  it  wraps  around  the  value  range. 
For  instance,  the  calculation  32767  +  1  produces  a  result  of 
-32768. 

This  means  that  numeric  comparisons  made  on  values  in  the 
range  32768  through  65535  deal  with  negatil^  ttutnbefs.  l&a 

should  limit  such  comparisons  to  tests  for  equality  or  non- 
equality.  Functions  such  as  LAND,  LNOT,  LOR,  and  LXOR  use 
integOT  values  but  produce  results  on  a  non-numeric,  bit-by-bit, 
basis. 

Division  of  an  integer  by  another  integer  yields  an  integer. 
BASIC09  discards  any  remainder. 

The  Real  Data  Type 

If  you  do  not  assign  a  data  type  to  a  variable,  BASIC09  assumes 
the  variable  is  real.  However,  programs  are  easier  to  understand 
if  you  define  all  variable  types. 

BASIC09  stores  as  real  values  my  eosistants  that  ham  diedmal 
points.  If  a  constant  does  not  have  a  decimal  point,  BASIC09 

stores  it  as  an  integer. 

BASIC09  requires  five  consecutive  memory  bytes  to  store  real 
numbers.  The  first  byte  is  the  exponent,  in  binary  two's  comple- 
ment. The  next  four  bytes  are  the  binary  sign  and  magnitude  of 
the  tnantissa.  The  mantissa  is  tn  the  flrat  81  hitis;  the  sign  dt 
the  mantissa  is  in  the  last  (least-significant)  bit  of  the  last  byte. 
The  following  illustration  shows  the  memory  storage  of  a  real 
number: 
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Internal  Representation  of  Real  Numbers 


exponent 


-r 


mantissa 


S 


byte:  0         12      3  4 

The  exponent  covers  the  range  2.938735877xl0-='s  (2-1^8) 
through  1.701411835xlO«»  (2^  as  powers  of  2.  Operations  that 

result  in  values  out  of  the  representation  range  cause  an  over- 
flow or  underflow  error.  You  can  handle  such  errors  using  the  ON 
ERROR  command. 

The  mantissa  mvmm  the  range  0.5  through  .^991939995  in  steps 
of  2"^^  This  means  that  real  numbers  can  represent  values 
.0000000005  apart.  BASIC09  rounds  operation  values  that  Ml 
between  these  paints  to  the  nearest  point. 

Because  floating  point  arithmetic  is  inherently  inexact,  a 
sequence  of  operations  can  produce  a  cumulative  error.  Proper 
rounding,  as  implemented  in  BASIC09,  reduces  the  effect  of  this 
problem,  but  cannot  eliminate  it.  When  using  real  quantities  in 
comparisons,  be  sure  your  computations  can  produce  the  exact 
value  you  desire. 


String  Variables 

A  string  is  a  vailable-length  seqpieaice  of  ASCII  values.  The 
length  can  imey  fyom  0,  a  m&  Alng,  to  the  capacity  d  the 
memory  available  to  BASIOOi, 

'%u  can  define  a  string  variable  either  explicitly,  using  the  DIM 
statement,  or  implicitly  by  appending  the  dollar  sign  ($)  to  the 
variable  identifier  (variable  name).  5br  example,  titlef  implicitly 
identifies  a  string  variable. 

Unless  you  specify  otherwise,  BASIC09  assigns  a  maximum 
string  length  of  32  characters.  Using  the  DIM  statement,  you 
can  specify  a  maximum  length  either  less  than  or  greater  than 
32.  To  conserve  memory,  use  DIM  to  assign  only  the  maximimi 
lenglh  ym  need  for  any  string  variable. 

The  beginning  of  a  string  is  always  Character  1.  Tbm  BASE 
statement,  which  sets  numeric  variable  base  niunbers  as  either  0 
or  1,  does  not  affect  string  variables. 
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If  an  operation  results  in  a  string  too  long  to  fit  in  the  assigned 
maxinniin  storage  space,  the  system  truncates  the  string  on  the 
right.  It  does  not  produce  an  error. 

String  storage  is  fixed  at  the  dimensioned  length.  The  sequence 
of  actual  string  byte  values  is  terminated  by  the  value  of  zero,  or 
by  the  maximum  length  allotted  to  the  string.  Any  onussd  stor- 
age after  the  zero  byte  allows  the  stored  string  to  ®pand  and 
contract  within  its  assigned  length. 

The  following  example  shows  the  internal  storage  of  a  variable 
dimensioned  as  string  16  1  and  assigned  the  value  "SAM". 
Note  that  Byte  4  contains  the  string  terminator  00.  The  string 
does  not  use  bytes  following  00. 


S 

A 

M 

00 

byte: 

1 

2 

3 

4 

S 

6 

If  you  assign  the  value  "ROBERT"  to  the  variable,  BASIC09  does 
not  need  to  terminate  the  string  with  00  because  the  string  is 
full: 

R 

0 

B 

E 

R 

T 

byte: 

1 

2 

3 

4 

5 

6 

The  way  BASIC09  handles  string  storage  is  important  when  you 
write  programs.  If  you  do  not  specify  a  length  for  strings  you 
define,  the  system  uses  the  default  length  32.  As  you  can  see, 
this  wastes  computer  memory  if  you  store  strings  of  only  four  or 
five  characters. 


The  Boolean  Type 

A  Boolean  operation  always  returns  either  the  character  string 
"TRUE"  or  "E!^LSE".  You  cannot  use  the  Boolean  data  type  for 
numeric  computation — only  for  comparison  logic. 

Do  not  confuse  the  Boolean  operations  AND,  OR,  XOR,  and  NOT 
(which  operate  on  the  Boolean  values  TRUE  and  E\LSE)  with 
the  logical  functions  LAND,  LOR,  LXOR,  and  LNOT  (which  use 
integer  values  to  produce  numeric  results  on  a  bit-by-bit  basis). 
An  attempt  to  store  a  non-Boolean  value  in  a  Boolean  variable, 
causes  an  error. 
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Automatic  Type  Conversion 

When  an  operation  mixes  numeric  data  types  (byte,  integp»  Of 
real  values),  BASIC09  automatically  and  temporarily  converts 
the  values  to  the  type  necessary  to  retain  accuracy.  This  conver- 
sion lets  you  use  numeric  quantities  of  mixed  types  in  most 
calculations. 

The  system  returns  a  type-mismatch  error  when  an  expression 
includes  types  that  cannot  legally  mix.  These  errors  are  reported 
by  the  second  compiler  pass,  which  occurs  automatically  when 
you  exit  the  mode. 

Because  type  conversion  takes  additional  execution  time,  you  can 
speed  calculations  by  using  values  of  a  single  type. 

Constants 

Constmtts  are  Values  in  a  program  that  do  not  change.  They  can 
use  any  of  the  five  data  types.  The  following  are  examples  of  con- 
stants in  a  procedure: 

HDME$="Fort  North" 
VALUE$="$25,000 
VALUE =2 5 

pmmm=m.m 

ANSWER="TRUE" 
MEMDRY=$0CFF 
PRINT  "The  End" 

Numeric  constants  are  either  integers  or  real  numbers.  If  a 
numeric  constant  includes  a  decimal  point  or  uses  the  "E  format" 
exponential  form,  it  causes  BASIC09  to  store  the  number  in  the 
real  format,  even  if  it  could  store  the  number  in  integar  or  byte 
format. 

You  can  use  this  feature  to  force  a  real  format.  For  instance,  to 
make  the  number  12  a  real  number,  type  it  as  12.0.  You  might 
want  to  force  real  values  in  this  way  when  all  other  values  in  an 
expression  are  real  so  that  BASIC09  does  not  have  to  do  a  time- 
consuming  type  conversion  at  run  time. 
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BASIC09  also  stores  as  real  numbers  any  numbers  that  do  not 
have  decimal  points  but  that  are  too  large  to  store  as  integers. 
Here  are  some  examples  of  legal  real  constants: 

1.0  9.8433218  -.01 

-999.000099     100000000  5644.34532 
1.95E  +  12  -999ii.9E-33 

BASIC09  treats  numbers  that  do  not  have  a  decimal  polsat  and 
are  in  the  range  -32768  through  -I-  32767  as  integers.  Ytm  must 
always  precede  hexadecimal  numbers  with  a  dollar  sign. 

Following  are  examples  of  legal  integer  constants: 

12  -3000  55 

$20  $FF  $09 

0  -12  -32768 

String  Constants 

A  string  constant  consists  of  a  sequence  of  characters  enclosed  in 
double  quotation  marks,  such  as: 

"The  End" 

To  place  a  string  constant  in  a  string  type  variable,  use  the 
equal  symbol  in  this  manner: 

TITLE$    =    "Masters    Of  Magic" 

To  include  double  quotation  marks  within  a  string,  use  two  sets 
of  double  quotation  marks^  like  this: 

"An  ""older  man""  is  wiser-." 

A  string  can  contain  characters  that  have  ASCII  values  in  the 
range  0  through  255. 

Variables 

In  BASIC09,  a  variable  is  local  to  the  procedure  in  which  it  is 
defined.  A  variable  defined  in  one  procedure  has  no  meaning  in 
another  procedure  unless  you  use  the  RUN  and  PARAM  state- 
ments to  pass  the  variable  when  you  call  the  o^er  procedure. 

The  local  nature  of  variables  lets  you  use  the  same  vatriahle 
name  in  more  than  one  procedure  and,  unless  you  specify  other- 
wise, have  the  variables  operate  independently  of  each  other. 
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Ifojyi  ean  assign  variables  using  either  the  LET  statement  with 
the  assign  symbol  ( = ),  or  by  using  the  assign  symbol  alone.  Ibr 
instance,  both  the  folbwing  command  lines  are  legal: 

LET  PAYMENT=44 . 50 
PAYMENT  =  4'1  .50 

When  you  call  a  procedure,  BASIC09  allocates  storage  for  the 
pBiisSw®'^  variables.  It  is  not  possible  to  force  a  variable  to 
occupy  an  absolute  address  in  memory.  When  you  exit  a  proce- 
dure, the  system  returns  the  storage  allotted  for  variables,  and 
you  lose  the  stored  values. 

If  you  write  a  procedure  to  call  itself  (a  recursive  procedure),  the 
call  creates  separate  storage  space  for  variables. 

Note:  Unlike  other  BASICS,  BASIC09  does  not  automati- 
cally initialize  variables  by  setting  them  to  mr&.  When  you 

execute  a  procedure,  all  variables,  arrays,  and  structures 
have  random  values.  Your  procedure  must  initialize  the 
variables  you  specify  to  the  values  you  require. 


Paisiiptg  Variables 

When  one  procedure  passes  variable  values  to  another  procedure, 
BASIC09  refers  to  the  passed  variables  as  parameters.  You  can 
pass  variables  either  by  reference  or  by  value. 

BASIC09  does  not  protect  variables  passed  by  reference.  There- 
fore, the  called  procedure  can  change  the  values  and  return  the 
new  values.  BASIGG9  does  protect  variables  passed  by  value,  so, 
the  called  program  cannot  change  them. 

To  pass  a  parameter  by  reference,  enclose  the  name  of  the  vari- 
able in  parentheses  as  part  of  the  RUN  statement  in  this 
manner: 

RUN  RflNDOMC10J     passes  the  value  10  to  a  procedure 

called  Random 

The  system  evaluates  the  storage  address  of  each  passed  vari- 
able, and  sends  the  variable  to  the  called  procedure.  The  called 
procedure  associates  the  storage  addresses  with  the  names  in  its 
local  PARAM  statement.  It  then  uses  the  storage  area  as  though 
it  had  created  it  locally.  This  means  it  can  change  the  value  of 
the  parameter  before  returning  it  to  the  calling  procedure. 
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lb  pass  parameters  by  value,  write  the  value  to  be  passed  as  an 
KKpression.  BASIC09  evaluates  the  expression  at  the  time  of  the 
call.  To  use  a  variable  in  an  expression  without  changing  its 
value,  use  null  constants,  such  as  0  for  a  number  or  ""  for  a 
string,  in  this  manner: 

RUN  ADDCOLUMNCx  +  0)  passes  the  value  of  x  by 

value 

RUN  TRANSLATECw$  +  "")         passes  the  contents  of  w$  by 

value 

To  pass  parameters  by  value,  B^&lGQ9  creates  a  temporary  vari- 
able. It  places  the  result  of  the  expression  in  the  temporary  vari- 
able and  sends  the  address  to  the  called  procediire.  This  means 

that  the  value  given  to  the  called  procedure  is  a  copy  of  the 
result  of  the  expression,  and  the  called  procedure  cannot  change 
the  original  value. 

The  results  of  expressions  containing  numeric  constants  are 
either  integer  or  real  values;  there  are  no  byte  constants.  To 
send  byte-type  variables  to  a  procedure,  pass  the  values  by  refer- 
ence. Therefore,  if  a  RUN  statement  evaluates  an  integer  as  a 
parameter  and  sends  it  to  a  byte-type  variable,  the  byte  variable 
uses  only  the  high-order  byte  of  the  two*^t6  integer. 

Arrays 

An  array  is  a  group  of  related  data  values  stored  consecutively 
in  memory.  The  system  knows  the  entire  group  by  a  variable 
name.  Each  data  value  is  an  element.  You  us©  a  mb&e^t  to  refer 
to  any  element  of  the  array.  For  example,  an  array  named  Graf 
might  contain  five  elements  referred  to  m'. 

0R||Ft1>      GtftFt^l      ©tftF«3>      ®t«FC4a  ©RArC5> 

Yatx  can  use  @aeh  of  these  elements  to  stcnre  a  different  value, 
such  as: 

GRAFCI  )  =  25 

GRAF(2)  =  47 

GRAFO)  =  39 

GRAFC4)  =  18 

GRAF(i>  -  SB 
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Note:  Normally,  array  elements  start  with  1  in  BASIC09. 
However,  you  can  use  the  BASE  command  to  cause  array 
elements  to  begin  at  0. 

The  previous  example  illustrates  a  single-dimensioned  array.  The 
elements  are  arranged  in  one  row  and  only  one  subscript  is  used 
for  each  element. 

The  following  procedure  lets  you  type  values  for  a  GRAF  array, 
and  displflys  to  results  in  a  simple  graph. 

PROCEDURE  GRAF 
□DIM  GRAFC5) : REAL 
□SHELL   "DISPLAY  0G" 
□FOR  T=1    TO  5 

DPtlNT  "V^lue  for   Item  #"5  Tj  ••D"; 

□INPUT  GRAFCt) 

□NEXT  T 

□PRINT 

□PRINT 

QPRIKT  '"This  is  hm  ywur  graph  staefcs  up,,." 

□PRINT 

□FOR  T=1   TD  B 
□PRINT  "Item  T;  "D" ; 

QFDR  U=1  TO,  SRAFCT) 
□PRINT  CHRf<79); 

□NEXT  U 
□PRINT 

□PRINT 
□  END 

This  program  uses  a  single  dimension  array — in  effect,  a  list. 

You  can  also  create  arrays  with  more  than  one  dimension  — 
more  than  one  element  for  each  row.  You  might  use  a  two-dimen- 
sioned array  in  a  program  to  store  names  and  addresses.  Instead 
of  creating  separate  arrays  for  the  name,  address,  and  zip  code, 
you  could  set  up  one  array  with  two  dimensions. 
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The  following  program,  used  to  enter  the  names  of  a  CQinpany's 
employees,  shows  how  this  might  be  done.  See  the  second  Ifne  for 
the  DIM  syntax.  When  you  run  the  procedure,  it  asks  you  for  a 
name,  address,  and  zip  code  for  each  of  10  employees.  After  you 
type  the  information  fot  all  the  entries,  the  procedure  displays 
the  information  on  the  screen. 

PROCEDURE  Names 

DDIM  NAMEC10,3):STRING 

□SHELL  "DISPLAY  0C" 

□BASE  a 

□FOR  T=0  TO  9 

□PRINT  "Type  Employee  Name  No.";  T;   " :   " ; 
□INPUT  NAME(T,0) 

□PRINT  "Type  Employee  Address  No,";  T;   "s  "; 
□INPUT  NAMECT,1 ) 

QPRINT  "Type  Employee  Zip  Code  No.";  T;   "s  "; 
□INPUT  NAMECT,2) 
□NEXT  T 

□SHELL   "DISPLAY  06" 

□PRINT  "And  the  names  ai-e..." 

□PRINT 

□FDR  T=0   TO  9 

□PRINT  NAMECT.B);    "□" ;    NAME(T,1);    "□" ;  NAMECT,2) 

□NEXT  T 
□  END 

The  DIM  statement  reserves  space  in  memory  for  a  string  array 
named  Name,  with  two  dimensions.  As  you  enter  data,  the  Name 
field  is  stored  in  Name{0,0),  Named  ,0),  Name(2,0),  and  so  on. 
The  Address  field  is  stored  in  Name(0,1),  Name(1,1), 
Nametgyl  J,  mtlA  M  CR,  Th#  Zip  field  is  stored  in  Name(0,2), 
Named, 2),  NameC2,2>,  and  SO  on.  This  continues  xintil  you  fill 
the  grid,  10  entries  with  three  items  each. 

lffi)U  can  also  create  arrays  with  three  dimensions.  The  following 
program  adds  one  more  dimension  that  keeps  track  of  each 
employee's  company.  It  dimensions  Name$  as  Name$ (2 , 1  0  , 3). 
Tim  first  dimension  contains  either  0  or  1  to  indie&t©  to  which 
company  the  employee  belongs. 
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PROCEDURE  names2 

□D I M  N AME*  (  a  r1  f  ,3* s  St:R  I MG 

□SHELL  "DISPLAY  0C" 

□BASE  0 

□FDR  X=0  TO  1 

□PRINT 

□PR  I  NT 

□FOR  T=0  TO  9 
□PRINT 

□IF  X=0  THEN 

i3P8INT  "Type  a  Wiggleworth  Company  employee 
riame ..." 

□ELSE 

□PRINT  "Type  a  Putforth  Company  employee  name..." 

□PRINT  "Type  Name  No.";  T;  ":  "; 
□INPUT  NAME$CX,T,0) 

□PRINT  "Type   Address   No.";   T;   ":  "i 
□INPUT  NAME$(X,T,1 ) 
□PRINT  "Type  2lp  Code  No."s  Xi 
□INPUT  NAME$CX,T,2> 

□NEXT  T 
□NEXT  X 

□SHELL  "DISPLAY  0C" 

□PRINT  "The  Uligglewsrlh  employees  are..." 

□PRINT 

□X  =  0 

DFOR  T«0  TO  9 

DPRINT  NAME$CX,,T,0J  -,  "□";   NAME$ ( X  , T ,  1  )  ;   "□"  ; 
NAME$(X ,T,2) 

□NEXT  T 
□PRINT 

□PRINT  "The  Putforth  GoMpa'ijy  employeea  are..." 
DPR  I  NT 

nx=i 

OFDR  T=0   TO  9 

□PRINT  NAME$CX,T,0);   "D" ;   N AME $ ( X , T , 1 ) ;   "□"  ; 
NfiME$CX ,T,2) 
□NEXT  T 
□END 
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The  easiest  way  to  understand  three  dimensional  arrays  is  to 
consider  the  first  dimension  as  a  page.  In  other  words,  if  the  first 
dimension  in  the  string  is  0,  the  employee  is  on  the  Wiggleworth 
Company's  page.  If  the  first  dimension  in  the  string  is  1,  the 
employee  is  on  the  Putforth  Cranpany's  page. 

Complex  Data  Types 

In  addition  to  the  five  standard  data  types,  you  can  create  your 
own  data  types.  Using  the  TYPE  command,  you  can  define  a 
new  data  type  as  a  vector  (a  single-dimensioned  array)  of  any 
previously  defined  type. 

Jbr  example,  in  the  previous  program,  the  Name  variable  can 
contain  only  one  tyTpe  of  data,  the  string  type.  However,  using 
the  TYPE  command  you  can  create  a  variable  that  accepts  sev- 
eral data  types. 

Suppose  you  create  an  employee  list  procedure  that  uses  the  fol- 
lowing variables,  of  the  following  size  and  tjrpes: 


Name 

Length 

Contents 

Type 

Name 

25 

employee  name 

string 

Street 

20 

street  address 

string 

City 

10 

city  of  address 

string 

Zip 

address  zip  code 

integer 

Sex 

false  =  male,  true  =  female 

Boolean 

Age 

employee  age 

bj^e 

You  can  combine  all  these  variables  into  one  complex  data  type. 
To  do  so,  dimension  the  variables  within  a  TYPE  command  Une, 

TYPE  EWPLOYEi-NAMEsSTRIN©[2S3  5  STREET :STR IN© £201 5 
CITYtSTRINGCI 0] ;  ZIPiREAL;  SEX:BOOLEAN;  AGE:BYTE 

This  creates  a  new  BASIC09  type,  called  Employee.  Employee 
requires  its  variables  to  have  six  fields  of  the  name,  size,  and 
type  shown  in  the  previous  chart. 

Once  you  create  the  new  data  type,  you  can  define  variables  to 
use  it.  For  instance,  the  following  program  line  defines  Worker  as 
type  employee,  with  10  ^laumti  ia  the  EUpray: 

□DIM  WQRKERC1 0) :EMPLOYEE 
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To  put  the  employee  data  type  to  work,  collect  your  data  with 
INPUT  commands.  Then,  store  the  data  into  the  new  Workra: 
array.  The  Mlowing  program  demonstrates  how  you  might  do 

this: 

PROCEDURE  worker 

DREW  DlmeBBion  variables  for  input 

ODIM  NM:STRING[25] 
□DIM  ST:STRING[20] 
□DIM  CTY:STRINGC10] 
□DIM  ZP:REAL 
□DIM  SX:BDDLEAN 
□DIM  AG: BYTE 

□REM  Create   new   type  and  array   using  new 

type 

□TYPE  EMPLDYEE  =  NAME:STRING[25] ;  STREET : STR I NG [ 20  I ; 
CrTYiiTilNSCIf  1;  ZlPsRIALj  SEX sB'OQUEAHl i  fltE:lYTE 
□DIM  WDRKERC10):EMPLOYEE 

□REM 

DFDR  T=1   TO  10 

□  INPUT  "N;aroe!D",NM 
□INPUT  "Street :D",ST 

□  INPUT  "City  :D",CTY 
□INPUT  "Zip:D",ZP 

□  I  NPUT  "Sex  sO'SSX 
□INPUT  "Age:n",AG 

□REM  Store  input   in  the  Worker  array  using 

field  names 

□WORKER(T).NAME=NM 

□WDRKERtT) . STREET-ST 

□WORKER(T).CITY=CTY 

□WORKER(T) .ZIP=ZP 

□WORKERCT) . SEX=SX 

□WDRKERCT).AGE=AG 

□PRINT 

□PRINT  "•  •*•••»••*♦»»»»*••»»" 

□PRINT 
□NEXT  T 

□SHELL  "DISPLAY  COO" 

□PRINT  "The  names  in  your  files  wow  are..." 

□PRINT 

□FDR  T=1    TD  10 
□PRINT  NDRKERfT) . NAME 
□PRINT  WDRKERCT). STREET 
OPR I  NT  WORKER (  T3 . C I TY 
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□PRINT  NORKERCT) .ZIP 
□IF  NDRKER(T).SEX=TRUE 
□THEN  PRINT  "Female" 
□ELSE 

□PRINT  "Male" 

□ENDIF 

□PRINT  WDRKER(T) . AGE 
□PRINT 

PPRINT  "•*•*••»♦*«•»»»•••♦••" 
DPR  I  NT 
DNEXT  T 

Note  that  the  Sex  field  is  defined  as  Boolean.  This  means  that 
you  can  respond  only  in  two  ways,  TRUE  or  FALSE.  The  method 
of  input  requires  only  one  byte  of  storage.  To  use  this  data  you 
need  to  handle  it  so  TRUE  and  FALSE  indicate  female  and  male. 

Complex  data  types  can  contain  more  than  one  field.  Each  field 
can  be  of  any  data  type.  You  reference  the  fields  of  a  complex 
data  type  by  typing  the  variable  name,  its  array  index,  a  period 
(.),  and  the  field  name.  The  following  lines,  from  the  Worker  pro- 
cedure, show  how  BASIC09  stores  the  data  from  the  input  lines 
into  ths  Worker  variable: 

WDRKERCT) . NAME=NM 
NDRKER<T) . STREET=ST 
NDRKER(T) .CITY=CTY 
WORKER(T) .ZIP=ZP 
WDRKER(T>.SE)(  =  SX 

These  lines  store  the  values  in  the  variables  NM,  ST,  CTY,  ZP, 
SX,  and  AG  into  the  NAME,  STREET,  CITY,  ZIP,  SEX,  and 
AGE  fields  of  the  Worker  variable.  This  operation  is  within  a 
FOR/NEXT  loop  that  uses  T  as  a  counter.  In  the  procedure,  T 
can  refer  to  a  value  in  the  range  1  to  10. 

The  procedure  uses  the  smm  t^e  ^  operation  to  m^mst  the 
data  from  the  comply  data  type  variable: 
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PRINT  WORKER(T) . NAME 
PRINT  WDRKER(T)  .STREET 
PRINT  NDRKER(T).CITY 
PRINT  WORKER(T) .ZIP 

IF  Wd!9l?ER«T).ilI-TRUE  THEN  PRINT  "Female" 

ELSE  PRINT  "Male" 

ENDIF 

PRINT  WDRKERCTJ.AGE 

Using  the  same  methods,  you  can  create  complex  data  types  that 
combine  other  complex  data  types  and  standard  data  types. 

The  elements  of  a  complex  structure  can  be  copied  to  anotbsr 
similar  structure.  Using  a  single  assignment  operator,  you  eaii 
write  an  entire  structure  to,  or  read  an  entire  structure  from, 
mass  storage  as  a  single  entity.  For  example: 

PUT  #2,  WDRKERCT) 

Because  the  system  defines  the  elements  of  complex-type  storage 
during  compilation,  it  need  not  do  so  during  runtime.  This 
means  that  BASIC09  can  re&rence  complex  structure  faster  than 
it  can  reference  arrays. 
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Expressions,  Operators,  and 
Functions 


ManipulaUng  Data 

BASIC09  uses  expressions  to  manipulate  data.  (Expressions  are 
pieces  of  data  connected  by  operators.) 

An  operator  is  a  symbol  or  a  word  that  signifies  some  action  to 
be  performed  on  the  specified  data.  Bach  data  item  is  a  vaUm. 

Expressions 

When  an  expression  is  evaluated,  the  result  is  a  value  of  some 
data  type  (real,  integer,  string,  byte,  or  Boolean). 

An  expression  might  look  like  this: 


First 
Value 

First 
Operator 

Second 
Value 

Second 
Operator 

Result 

6 

+ 

5 

11 

or  like  this: 

First 
Vklue 

First 
Operator 

Second 
\^lue 

Second 
Operator 

Result 

"Seaside" 

+ 

"Villa" 

Seaside 
Villa 

When  BASIC09  evaluates  an  expression,  it  copies  each  value  onto 
an  expression  stack.  Functions  and  operators  take  their  input 
values  from  this  stack  and  return  their  results  to  it.  Many 
expressions  result  in  assignments,  as  do  the  examples  shown. 
The  BASIC09  makes  the  resulting  assignment  only  after  it  com- 
putes the  entire  expression.  This  lets  you  use  the  variable  that  is 
being  modified  as  one  of  the  values  in  the  expression,  such  as  in 
this  sample: 

X  =  X  +  1 
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The  result  of  an  expression  is  always  one  of  the  five  BASIC09 
data  types.  However,  you  can  often  mix  data  types  within  an 
expression  and,  in  some  cases,  the  result  of  an  expression  is  of  a 
difTerent  data  type  than  any  of  the  values  in  the  exgir^mkfti- 
Saeh  is  the  mm  if  you  use  ^im  kmMmm  spuhd  in  ttiis 
maimer: 

24  <  100 

The  less-than  operator  compares  two  integer  values.  The  result 
of  the  comparison  is  Boolean;  in  this  case,  the  value  is  TRUE. 

Conversion 

Because  BASIC09  performs  atitottiatlG  type  eenivBrsion  of  values, 
you  can  mix  any  of  the  three  numeric  data  types  in  an  expres- 
sion. When  you  mix  numeric  data  types,  the  result  is  always  of 
the  same  type  as  the  value  having  the  largest  representation,  in 
this  order:  real  <  integer  <  byte. 

You  can  use  any  numeric  type  in  an  expression  that  produces  a 
real  number.  If  you  want  an  expression  to  produce  a  byte  or  inte- 
ger type  value,  the  result  must  be  small  enough  to  fit  the 
desired  type. 

Operators 

BASIC09  has  operators  to  deal  with  all  types  of  data.  Each  oper- 
ator, except  NOT  and  negation  (unary  -),  takes  two  values  or 
operands,  and  performs  an  operation  to  produce  a  result.  MOT 
can  accept  only  one  value.  The  following  table  lists  the  operators 
available  and  the  types  of  data  they  accept  and  produce. 

Because  the  same  operators  function  on  the  three  types  of 
numeric  data  (byte,  integer,  and  real),  these  tj^es  are  referred  to 
by  the  operand  type  "numeric." 
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BASIC09  Expression  Operators 


Operand 

Result 

viper  axor 

r  vuicuQii 

Type 

lype 

— 

Negation 

TsmmAc 

numeric 

Exponentiatto 

ntnneric 

numeriie 

Multiplication 

numeric 

numeric 

/ 

Division 

numeric 

numeric 

+ 

Addition 

numeric 

numeric 

Subtraction 

numeric 

numeric 

NOT 

Logical  Negation 

Boolean 

Boolean 

AND 

Logical  AND 

Boolean 

Boolean 

OR 

Logical  OR 

Boolean 

Boolean 

XOR 

Logical  Exclusive  OR 

Boolean 

Boolean 

+ 

Concatenation 

string 

string 

Equal  to 

all  types 

Boolean 

<>  or  >< 

Not  equal  to 

all  types 

Boolean 

< 

Less  than 

numeric,  stringt 

Boolean 

<=  or  =< 

Less  than  or  equal 

numeric,  stringt 

Boolean 

> 

Greater  than 

numeric,  stringt 

Boolean 

>=  or  => 

Greater  than  or  equal 

numeric,  stringt 

Boolean 

t  When  comparing  strings,  BASIC09  uses  the  ASCII  values  of 
characters  as  the  basis  for  comparison.  Therefore,  0  <  1,  9  <  A, 
A  <  B,  A  <  b,  b  <  z,  and  so  on. 


Arithmetic  Operators 

Arithmetic  operators  perform  operations  on  numeric  data.  There- 
fore, both  operands  in  the  expression  must  be  numeric.  The  fol- 
lowing table  lists  the  arithmetic  operators. 

Negation  The  single  dash  negates  a  number's  sign: 

-10  is  negative  10. 

Exponenlialfon     Use  a  caret  O  or  two  astiesdsks  (**)  to  raise 
a  number  to  a  power:  2*3  is  8  (2  x  2  x  2). 
Similarly,  2**3  is  8. 

Multiplication        A  single  asterisk  causes  multiplication: 
2  *  3  is  6. 


Division 


A  slash  causes  division:  6  /  2  is  3. 
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Addition  The  plus  sign  causes  addition:  3  +  3  is  6. 

Subtraction  A  dash  causes  subtraction:  6  -  3  is  2. 

BASIC09  TttseS  thfe  standard  hierarchy  of  operations  ^en  calcu- 
lating expressions  with  multiple  operators.  This  means  that 
BASIC09  has  an  order  in  which  it  performs  calculations  involv- 
ing more  than  one  operator. 

The  following  BASIC 09  operators  are  listed  in  order  of 
precedence: 

NOT     -  (negate) 

** 

•  / 
+ 

>        <   <>    =    >=  <= 
AND 

OR  XOR 
Also,  BASIC09: 

•  Performs  operations  enclosed  in  parentheses  before  oper- 
ations not  in  parentheses. 

•  Performs  the  leftmost  operations  first  when  two  or  mdfe 
operations  are  of  equal  precedence. 

%u  can  use  parentheses  to  override  this  standard  precedence. 
Fbr  sample: 

t  ♦  1  «  3  =  S 

but 

<  2  +  1    )  »  3  =  9 

ThiS  folliowifltg  examples  show  BAfflOOQ  ^regsidtis  dii  the  1^, 
and  the  way  BASIC09  evaluates  them  on  the  right.  You  can 
enter  the  expressions  in  either  form,  but  the  decompiler  gener- 
ates the  simpler  form,  shown  on  the  left. 
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BASIC09 
Representaibin 

Eqiilvalent 

a  =  b  +  c**2/d 

a  =  b  +  ((c^*2)/d) 

a  =  b>c  AND  d>e  OR 

a  =  ((b>c)  AND  (d>e)) 

G  =  e 

OR  (c=e) 

a=(b  +  c+dye 

a=((b+e)+d)/e 

a=b**G**d/e 

a=(b**(G**d))/e 

a=  -(b)**2 

a=(-b)**2 

a==b=e 

Relational  Operators 

Relational  operators  make  logical  comparisons  of  any  type  of  data 
and  return  a  result  of  either  TRUE  or  PALSE.  An  explanation  of 
the  relational  operators  follows.  All  relational  ^serators  have 
equal  precedence. 

=  Equal.  Returns  TRUE  if  both  operands  are 

equal,  or  FALSE  if  they  are  not  equal. 

<  Less  than:  Returns  TRUE  if  the  first  operand  is 
less  than  the  second,  or  E^.LSE  if  is  not. 

>  Greater  than:  Returns  TRUE  if  the  first  operand 
is  greater  than  the  second,  or  FALSE  if  it  is  not. 

<>  or  ><       Unequal:  Returns  TRUE  if  the  operands  are  not 
equal  or  E^LSE  if  they  are. 

<  =  or  =  <      Less  than  or  equal  to:  Returns  TRUE  if  the  iwt 

operand  is  less  than  or  equal  to  the  second 
operand.  Otherwise,  the  operation  returns 
FALSE. 

>  =  or  =>      Greater  than  or  equal  to:  Returns  TRUE  if  the 

first  operand  is  greater  than  or  equal  to  the 
second.  Otherwise,  the  operaticm  retess  lALSE. 
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You  normally  use  relational  operators  in  IF/THEN  statements. 
Pbr  example,  if  your  procedure  has  two  numeric  variables,  Pay- 
ments and  Income,  you  might  include  command  lines  like  this: 

IF  PAYMENTS  >  INCOME  THEN 

PRINT  "You're  iroke!" 
ENDIF 

When  you  combine  arithmetic  and  relational  operators  in  the 
same  expression,  BASIC09  evaluates  the  arithmetic  operations 
first,  fbr  sample: 

IF  X»Y/2  <"  14  THEN 

PRINT  "Average  Score  ia  ";  X»Y/2 
ENDIF 

BASIC09  performs  the  arithmetic  operation  x*y/2,  then  compares 
the  result  with  the  value  14. 

When  you  use  relational  operators  with  strings,  BASIC09  com- 
pares the  strings  character  by  character.  When  it  finds  two  char- 
acters that  do  not  match,  it  checks  to  see  ^^Ukti  character  has 
the  lower  ASCII  code  value.  The  string  containing  the  charact^ 

with  the  lower  value  comes  first. 

Consider  this  example: 

PRINT  "hunt"  >  "hung" 

BASIC09  compares  each  character  in  each  string.  Because  the 
first  three  characters  are  the  same,  the  result  of  the  operation  is 
based  on  the  comparison  of  t  and  g.  Because  t  (ASCII  value  = 
116)  is  "greater  than"  g  (ASCII  value  =  103),  the  con^n&ad 
prints  TRUE. 


String  Operators 

The  string  operator  is  the  plus  sign  (  +  ).  This  symbol  appends 
one  string  to  another.  All  operands  must  be  strings,  and  the 
resulting  value  is  one  string.  Examine,  for  example,  the  foUoW'- 
ing  line,  which  appoaAi  Sbffie  steclngs; 

PRINT  "My  fr tends  are  "  +  "Jack  and  "  +  "Jill." 

It  prints:  My  friends  are  Jack  and  Jill. 
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The  logical,  or  Boolean,  operators  make  logical  comparisons  of 
Boolean  values.  The  following  table  describes  the  results  yielded 
by  each  logical  operator  given  the  specified  TRUE/FALSE  values; 

Meaning  of  First  Second 

Operator  Operation  Operand    Operand  Result 


NOT 

The  result  is  the  opposite  of  TRUE 

FALSE 

the  operand. 

FALSE 

TRUE 

AND 

When  both  values  are  TRUE,  TRUE 

TRUE 

TRUE 

the  result  is  TRUE. 

TRUE 

FALSE 

FALSE 

Otherwise,  the  result  is 

FALSE 

TRUE 

FALSE 

FALSE 

FALSE 

FALSE 

OR 

When  both  values  are 

TRUE 

TRUE 

TRUE 

FALSE,  the  result  is  FALSE.  TRUE 

FALSE 

TRUE 

Otherwise,  the  result  is 

FALSE 

TRUE 

TRUE 

TRUE. 

FALSE 

FALSE 

FALSE 

XOR 

When  only  one  of  the  values 

TRUE 

FALSE 

is  TRUE,  the  result  is 

TRUE 

FALSE 

TRUE 

TRUE.  Otherwise  the  result 

FALSE 

TRUE 

TRUE 

is  FALSE. 

FALSE 

FALSE 

FALSE 

Use  logical  operators  in  IF/THEN  statements  such  as: 

IF  PftYMERTS  <   INCOME  AND   INCDME+SAVINGS  > 

PAYMENTS  THEN 

PRINT  "You'll   have   to   use  your    savings   to  get 
out   of  this  mess . " 
ENDIF 

Functions 

Functions  are  operation  sequences  the  system  performs  on  data. 
In  a  statement,  BASIC09  performs  functions  first.  Chapter  11, 
"Command  Reference,"  describes  the  following  functions. 
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Functions  returning  results  of  type  real 


SIN  Calculates  the  Mgmumetilc  sine  of  a  number. 

COS  Calculates  the  trigonometric  cosine  of  a  number. 

IAN  Calculates  the  trigonometric  tangmt  of  a  number. 

ASN  Calculates  the  trigonometric  arcsine  of  a  number. 

ACS  Calculates  the  trigonometric  arccosine  of  a  number. 

ATN  Calculates  the  trigonometric  arctangent  of  a 

number. 

LOG  Calculates  the  natural  logarithm  (base  e)  of  a 

number. 

LOGIO        Calculates  the  logarithm  (base  10)  of  a  number. 

EXP  Calculates  e  (2.71828183)  raised  to  the  specified 

positive  power. 

FLOAT       Converts  byte  or  integer  type  numbers  to  real 

numbers. 

INT  Calculates  the  largest  whole  number  less  than  or 

equal  to  'Uie  ^^Qed  number. 

PI  iep^mts  the  constant  3.14159265. 

SQB  Calculates  the  square  root  of  a  pu^tive  numb^. 

SQRT        CjaHmi&im  #ie  square  root  ctf  a  pastil®  Mjmber.  Its 
function  is  identical  to  SQE. 

RND  Returns  a  random  number. 
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Functions  returning  results  of  any  numeric  type 
The  resulting  type  depends  on  the  input  type. 

ABS       Calculates  the  absolute  value  of  a  number. 

SGN        Returns  a  value  to  indicate  the  sign  of  the  specified 
number  (-1  if  the  number  is  less  than  0,  0  if  the 
number  is  0»  cir  1  if  the  immber  la  grater  than  0). 

Calculates  the  square  of  a  number  . 

\AL       Converts  a  sta±ag  to  a  mimeric  value. 


FtEne^ns  rettmiliig  results  of  type  integer  or  i^fj^  l^te 


MOD 

ADDR 

SIZE 

ERR 
PEEK 

POS 

ASC 

LEN 
SUBSTR 


Rounds  a  real  number  and  converts  it  to  an 


Calculates  the  modulus  (remainder)  of  two 

numbers. 

Returns  the  absolute  memory  address  of  a 
vaiiables  m  mtw,  oe  n  itaructure. 

Returns  (in  %ies}  the  storage  size  of  a  variable, 
m.  arrayt  or  a  structure. 

Returns  the  mtm       ti  ibe       tmmt  error. 

Returns  the  byte  value  at  a  specified  memory 

address. 

Returns  the  current  character  position  of  the 
print  buffer. 

Returns  the  numeric  value  (ASCII  code)  of  a 

string  character. 

Returns  the  length  of  a  string. 

Retiurns  the  starting  position  of  the  specified 
subsfariog  idMa  a  ^»g,  or  returns  0  if  it 
cannot  find  the  substring. 
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Functions  performing  bit-by-bit  logical  operations  on  inte- 
ger or  byte  data  and  returning  integer  results.  Do  not  con- 
fuse     V  ""j  ictions  with  Boolean  type  operators. 


LAND 

Calculates  the  logical  AND  of  two  values. 

LOR 

Calculates  the  logical  OR  of  two  values. 

LXOR 

Calculates  the  logical  EXCLUSIVE  OR  of  two 

values. 

LNOT 

CSalemltttii  fcf  logical  NOT  of  a  value. 

Functions  returning  a  result  of  type  string 

CHR$ 

Returns  the  charaeter  having  a  specified  ASCII 

value. 

DATE$ 

Returns  the  system's  current  date  and  time. 

LEFT$ 

Returns  the  specified  number  of  characters 

beginning  at  the  leftmost  character  of  the 

specified  string. 

RIGHT$ 

Returns  the  specified  number  of  characters 

beginning  at  the  rightmost  character  of  the 

specified  string  and  counting  backward. 

MID$ 

Returns  the  specified  number  of  characters 

starting  at  the  specified  position  in  a  string. 

STR$ 

Converts  numeric  type  data  to  string  type. 

TRIM$ 

Removes  trailing  spaces  from  the  specified 

string. 

Fvmetions  retemlng  Boolean  values 

TRUE 

Always  returns  TRUE. 

FALSE 

Always  returns  E^LSE. 

EOF 

Tests  for  the  end  of  a  disk  file.  Returns  TRUE 

when  the  end  of  the  file  occurs. 
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Disk  Files 


When  you  tell  OS-9  or  BASIC09  to  store  (save)  data  on  a  disk,  it 
stores  the  data  in  a  logical  block  called  a  file.  The  term  logical 
means  that,  although  the  system  might  store  portions  of  a  file's 
data  in  several  different  disk  locations,  it  keeps  track  of  every 
location  and  triKits  the  scattered  data  as  thougli  it  dceupied  a 
single  block.  It  does  this  automatically  and  you  never  need  to 
worry  about  how  the  data  is  stored.  File  data  can  be  binary 
data,  textual  data  (ASCII  characters),  or  any  other  useful 
information. 

Because  OS-9  handles  all  hardware  input/output  devices  (disk 
drives,  printers,  tCTminals,  and  so  on)  in  the  same  manner,  you 

can  send  data  to  any  of  these  devices  in  the  same  way.  This 
means  you  can  send  the  same  information  to  several  devices  by 
clcKiging  the  path  the  data  follows.  For  example,  you  can  test  a 
procedure  that  communicates  with  a  terminal  by  transferring 
data  to  and  from  a  disk  drive. 

BASIC09  normally  works  with  two  types  of  files — sequential 
files  and  random  access  files.  The  following  chart  shows  file- 
access  options,  their  purposes,  and  the  keywords  with  which  to 
use  them: 


Types  of  Access  for  Files 


Access 

Type 

Function 

Use  with 

DIR 

Opens  a  directory  file  for  reading. 
Use  only  with  READ. 

OPEN 

EXEC 

Specifies  that  the  file  to  epen  or 

create  is  in  the  execution  directory, 
rather  than  the  data  directory. 

OPEN 
CKEATE 

READ 

Lets  you  read  data  from  the 
specified  file  or  device. 

OPEN 
CREATE 

WRITE 

Lets  you  write  data  to  the  specified 

file  or  device. 

OPEN 
CREATE 

UPDATE 

Lets  you  read  data  from  and  write 
data  to  the  specified  file  or  device. 

OPEN 
CREATE 
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Sequential  Files 

Sequential  files  send  or  receive  (WRITE  or  READ)  textual  data 
in  order,  the  second  item  following  the  first,  and  so  on.  You  can 
access  sequential  data  only  in  the  same  order  as  you  originally 
stored  it.  To  read  from  or  write  to  a  particular  section  of  a  file, 
you  must  first  read  through  all  the  preceding  data  in  the  file, 
starting  from  the  beginning. 

BASIC09  stores  sequential  file  data  as  ASCII  characters.  Each 
block  of  data  is  separated  by  a  delimiter  consisting  of  a  carriage- 
return  character  (ASCII  Character  13).  Because  BASIC09  uses 
this  delimiter  to  determine  the  end  of  a  record,  sequential  files 

can  contain  records  of  varying  length. 

Use  the  WRITE  and  READ  commands  to  store  and  retrieve  data 
in  sequential  files.  A  WRITE  command  causes  BASIC09  to 
transfer  specified  data  to  a  specified  file,  ending  the  data  with  a 
carriage  return.  A  READ  command  causes  BASIC09  to  load 
from  the  specified  file  the  next  block  of  data,  stopping  when  it 
reaches  a  carriage  return. 

Sequential  File  Creation,  Storage,  and  Retrieval 

BASIO0@  mm  the  CREATE  command  to  estaMl^  both  segnm- 
tial  and  random  access  files.  A  CREATE  statemait  contains: 

•  The  keyword  CREATE. 

•  A  path  number  variable  in  which  BASIC09  stores  the 
number  of  the  path  it  opens  to  the  new  file. 

•  A  comma,  followed  by  the  name  of  the  file  to  create. 

•  An  optional  colon,  followed  by  the  access  mode.  If  you  do 
not  specify  an  access  mode,  BASIC09  automatically 
opens  the  created  file  in  the  UPDATE  mode. 
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The  following  procedure  shows  how  to  create  a  file  and  write 

data  into  it: 

PROCEDURE  makefile 

DDIM  PflTHiBYTE  (*  establishes  a  variable 

□REM  for  the  path  number  to  the  file 


DCREftlE  #PflTH,"test"!WRlTE 

□WRITE  #PflTH,"Thi5  is  a  test" 
□NRITE  #PATH,"of  sequential  files. 
□CLOSE  *PATH 
□SHELL  "LIST  TEST" 
□END 


•  creates  the  file  TEST 

'  writes  data  to  the  file 
'  writes  another  line  of  data 
»  closes  the  path  to  the  file 
»  displays  the  file  contents 


The  first  line  of  the  procedure  dimensjtos  a  wiaMe  (P0ii}  to 
hold  the  number  of  the  path  that  CREATE  opens.  IMs  variaMe 
should  be  of  byte  or  integer  type. 

When  you  establish  a  new  file  with  CREATE,  you  automatically 
open  a  path  to  the  file.        do  not  need  to  use  the  OPEN 

command. 

The  preceding  procedure  writes  two  lines  into  a  file  named  Test. 
It  then  closes  the  path  and  uses  the  OS-f  Llif  command  to  dis- 
play the  contents  of  the  newly  created  file.  Yon  see  that  the  data 

is  successfully  stored  on  disk. 

The  next  procedure  shows  how  to  reopen  an  existing  file  for 
sequential  access,  read  the  contents  of  the  file,  and  append  data 
to  the  end  of  the  file. 

The  only  way  to  move  the  file  pointer  to  the  end  of  a  sequential 
file  is  to  read  all  the  data  already  in  the  file.  Once  the  pointer  is 
at  the  end  of  the  file,  you  can  add  data. 

PROCEDURE  append 

□DIM  PflTHiBYTE  (•  dimension  variable  to  hold  the  number  of  the 

□REM  path  to  the  opened  file. 

□OPEN  *PflTH,"test"!UPDATE  («  open  file  for  reading  and  writing, 

□READ  #PATH,line$  (•  read  the  first  element  of  the  file. 

IREAD  *PflTH, lines  (•  read  the  next  (the  last)  element. 

□WRITE  *PATH,"This  is  a  test"  (•  write  one  new  line  to  the  file. 

□WRITE  #PflTH,"of  appiftding  to  a  sequential  file."  (»  write  another. 

□CLOSE  *PATH  (♦  close  the  path. 

□SHELL  "LIST  TEST"  (•  display  the  file  with  the  new  lines. 

□END 
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Because  the  Test  file  already  exists,  this  procedure  uses  OPEN 
to  establish  a  path  to  the  file.  It  uses  the  UPDATE  mode  of  file 
access  because  it  needs  to  both  read  from  and  write  to  the  file. 

The  two  READ  statements  read  the  file's  contents  and,  as  a 
result,  move  the  file  pointer  to  the  end  of  the  file.  The  WRITE 
statements  then  appmi  new  lines.  Aft&t  elosixig  the  pa£h, 
the  procedure  calls  on  the  OS-9  LIST  command  to  display  the 
contents  of  the  file,  with  its  appended  lines. 

Changing  Data  in  a  Sequential  File 

'^1  can  also  change  data  anywhere  in  a  sequential  file.  How*- 
efuse,  if  your  changes  are  longer  than  the  original  data,  the  oj^m- 
ation  destroys  part  of  the  file.  To  change  data  in  a  sequenttal 

file,  read  the  data  preceding  what  you  want  to  change,  and  write 
the  new  data  to  the  file  in  this  manner: 

PROCEDURE  replace 
DDIH  P»Tf  iim 
DOPEN  »PflTH,"te5t";UPI)ATE 
DREAD  #PflTH,line$ 
DREfiD  #PflTH,liiie$ 

DWRITE  *PATH, "Let's  put  new"    (•  write  over  existing  3rd  and 
DMRITE  fflTN, "words  into  the  old  sequential  file."  (♦  «h  lines. 

□CLOSE  *PATH 
□SHELL  "LIST  TEST" 
DEND 

Notice  that  the  total  amount  of  data  in  the  two  new  lines  is 
exactly  the  same  as  in  the  two  old  lines.  You  can  replace  an 
existifig  line  with  ffewer  characters  by  padding  the  new  data 
with  spaces.  However,  if  you  try  to  replace  existing  lines  with 
longer  lines,  the  new  lines  write  over  and  destroy  other  data  in 
the  file. 
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INPUT  and  Sequential  Files 

Although  you  can  also  use  the  INPUT  command  with  sequential 
files,  doing  so  might  put  unwanted  data  into  them.  When  a  pro- 
cedure encounters  INPUT,  it  suspends  execution  and  sends  a 
question  mark  (?)  to  the  screen.  This  feature  makes  INPUT  both 
an  input  and  output  statement.  Therefore,  if  you  open  a  file 
using  the  UPDATE  mode,  INPUT  writes  its  prompts  to  the  file, 
destroying  data.  If  you  specify  text  to  be  displayed  with  the 
INPUT  command,  INPUT  writes  this  text  to  the  file  also. 

Random  Access  Files 

Random  access  files  store  data  in  fixed-  or  equal-length  blocks. 
Be^tise  ssi^  record  in  a  specific  file  is  the  same  size,  you  can 
easily  calculate  the  position  of  a  record. 

For  instance,  suppose  you  have  a  file  with  a  record  length  of  50- 
bytes  (or  characters).  To  access  Record  10,  multiply  the  record 
number  (10)  by  the  record  length  (50)  and  move  the  file  pointer 
to  the  calculated  position  (500). 

A  random  access  file  sends  and  receives  data  (using  PUT  and 
GIT)  in  a  binary  form,  exactly  as  BASIC09  stores  it  imternally. 
This  feature  minimizes  the  time  involved  in  converting  the  data 
to  and  from  ASCII  representation,  as  well  as  reducing  the  file 
space  required  to  store  numeric  data.  You  position  the  random 
access  file  pointer  using  SEEK.  Compared  to  sequential  file 
access,  random  file  access  using  GET  and  PUT  is  very  fast. 

Using  randdm  access  commands,  you  can  store  and  retrieve  indi- 
vidual bytes,  strings  of  bytes,  individual  elements  of  arrays  or 
total  arrays  with  one  PUT  or  GET  command.  When  you  GET  a 
structure,  fou  ricow  the  number  of  bjrtes  associated  with  that 
type  cC  stoieture. 

This  SOeans  when  you  GET  one  element  of  byte  type  data,  you 
read  one  byte.  When  you  GET  one  element  of  real  type  data,  you 
read  five  bytes.  If  you  GET  an  array,  you  read  all  the  elements  of 
the  array.  This  potential  for  reading  entire  arrays  at  once  can 
greatly  speed  di^  access. 

As  well  as  moving  the  file  pointer  to  the  beginning  (tf  individual 
records,  you  can  also  move  it  to  any  position  within  a  record  and 
begin  reading  or  writing  one  or  more  bytes  from  that  point. 
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Creating  Random  Access  Files 

"S)u.  create  and  open  r-andom  access  files  in  the  mm  ym 
create  and  open  sequential  files.  The  only  differences  are  in  the 

commands  you  use  to  store  and  retrieve  the  data  and  in  the 
manner  you  keep  track  of  where  elements,  or  records,  of  a  file 
hegia  ai^  end. 

Before  you  can  write  data  to  a  random  access  file,  you  must 
either  CREATE  it  or  open  it  in  the  WRITE  or  UPDATE  mode. 
Once  you  have  a  path  open  to  an  existing  file,  use  POT  to  write 
data  into  the  file.  If  you  open  the  file  in  the  READ  or  UPDATE 
mode,  you  can  then  use  the  GET  command  to  retrieve  data  from 
the  file. 

The  PUT  emamxei  can  use  only  one  parameter,  the  name  of  the 
data  element  to  i^We.  The  parameter  can  be  a  string,  a  variable, 
an  array,  or  a  complex  data  structure. 

Before  storing  data,  you  must  devise  a  method  to  store  it  in 
blocks  of  equal  size.  Knowing  the  unit  size  lets  you  later  retrieve 
the  data  in  its  original  form.  The  following  procedure  shows  one 
my  to  do  this: 

PROCEDUiE  put jet 

□REM  This  procedure  creates  a  file  named  Testl,  reads  18  data  lines, 
□REM  PUTS  them  into  the  file,  then  closes  the  file.  Next  it 
□REM  opens  the  file  in  the  READ  mode,  GETS  Stored  lines  and  lists 
□REM  them  on  the  display  screen. 

□DIM  LENGTH  I  BYTE 
□DIM  NULL;STRING[251 
□DIM  LINE;STRING[251 
□PJM  PATH:BYTE 
DLEfirfMS 
DNULL="" 
□BASE  e 

□ON  ERROR  GOTO  \t 

□DELETE  "testl"  (•  if  the  file  exists,,  delete  it. 

liQtFf  mm 

□CREATE  #PATH,"test1";WRITE  (•  create  a  file  named  testl. 
□FOR  ^'i  TO  9 

□SEEK  #PATH,LEN6TH»T  (•  find  be|innlng  of  each:  file. 

□READ  LINE$  (»  reasi.  a  line  of  Mt. 

□PUT  IPATH.LINEI  (♦  store  the  line  in  the  file, 
□NEXT  T 
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□CLOSE  IPATH 

(• 

close  the  file, 

□OPEN  #PATH,"te5tl'' 

READ 

U 

open  the  file  for  reading. 

nm  1-t  TO  9 

OSa  »WIM,L0iTli»T 

{• 

find  the  l).e|liij)jfl|  e-f  each  file 

DOET  ifPftTHiLINE 

(• 

get  a  line  frm  thfi  file, 

□PRINT  LINE 

(> 

display  the  litta. 

□NEXT  T 

□CLOSE  'PATH 

(t 

close  the  file. 

□END 

UDflTfl  "This  is  test 

line 

#1" 

DDftTfl  "This  is  test 

line 

12" 

□DATA  "This  is  test 

line 

#3" 

DDflTfl  "This  is  test 

line 

#4" 

□DATA  "This  is  test 

1  ine 

*5" 

□DATA  "This  is  test 

line 

#S" 

□DATA  "This  is  teat 

line 

n" 

□DATA  "This  is  test 

line 

#8" 

□DATA  "This  is  test 

line 

#9" 

□DATA  "This  15  test 

1  ine 

#10" 

This  procedure  creates  a  file  named  Testl.  The  variable  named 
Length  stores  the  length  of  each  line  in  the  file  (25  characters). 
The  string  variable  Null,  is  a  string  of  25  space  characters.  The 
variable  Line  contains  the  data  to  store  in  each  element  (record) 
in  the  file.  The  variable  Path  stores  the  path  number  of  the  file. 

Next,  the  procedure  contains  an  ON  ERROR  routine  that  deletes 
the  file  Testl,  if  it  already  exists.  Without  this  routine,  the  pro- 
cedtTO  p^^a&ss  an  ^or  if  you.  tssB&xie  it  more  tiban  once. 

Next,  the  routine  uses  CREATE  to  open  the  file  Itestl.  The  line 

SEE:k  #PATH,  length*!  sets  the  file  pointer  to  the  proper  loca- 
tion to  store  the  next  line.  Because  Length  is  established  as  25, 
the  file  lines  are  stored  at  0,  25,  50,  75,  and  so  on. 

After  the  routine  initializes  storage  space,  it  begins  to  store 
data  by  reading  the  procedure  data  lines  one  at  a  time,  seeking 
lite  paper  fifc  locatiMi,  mii  patting  the  data  into  the  file.  After 
storing  all  10  lines,  it  closes  the  file. 
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The  last  part  of  the  routine  opens  the  new  file,  uses  the  same 
SEEK  routine  to  position  the  file  pointer,  and  reads  the  lines 
back,  one  at  a  time,  to  confirm  that  the  store  routine  is 

successful. 

The  next  short  routine  shows  how  you  can  use  a  procedure  to 
read  any  line  ^nim  select  in  the  file,  without  riding  any  pireced- 
ing  lines: 

PROCEDURE  randomread 
DDIR  LENGTH; BYTE 
DDIM  L1NE:STRING[25] 
ODIM  SEEKLINEjBYTE 
DDIM  fflTHilYtl 
OLEN6TM»25 

□OPEN  #PftTH,'"test1"iR£ftD  (♦  open  the  file  for  reading. 

mm 

OINPUT'line  nitmber  to  display. .  .".SEEKLINE  (•  type  a  line  to  get. 
DEXITIF  5EEKLINE>1J  OR  SE£KLINE<1  THEN  (•  test  if  record  is  valid. 
DENDEXIT  («  exit  loop  if  not. 

OSEEK  #PflTH,{SEEKLlNE-1)«LEN6TH       l«  find  the  requMted  record. 
DGET  »PATH,LIHE  (•  read  the  record. 

□PRINT  LIKE  (•  display  the  record. 

□PRINT 
□ENDLDOP 

CIPRINT  "That's  all   "         (•  end  session. 

□CLOSE  #PftTH  (•  close  path. 

□END 

The  procedure  asks  for  the  record  number  of  the  line  to  display. 
When  you  type  the  number  (1-10)  and  press  |  enter  |,  SEEK  moves 
the  file  pointer  to  the  beginning  of  the  record  you  want,  GET 
r^tds  ft  into  the  '^uiable  Line,  and  FMNT  displays  it.  The  cal- 
culation cse:eklime-1  )»LENGTH  determines  the  beginning  of 
the  line  you  want.  If  you  type  a  number  outside  the  range  of 
lines  contained  in  the  file  (1-10),  the  procedure  drops  down  to 
Line  100  and  ends. 

By  changing  this  procedure  slightly,  you  can  replace  any  line  in 
the  pro^dure  with  another  line.  The  altered  procedure  below 
demonstrates  this: 
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PROCEDURE  random—replace 
□DIM  LENGTH: BYTE 
□DIM  LINE:STRING[25] 
□DIM  SEEKLINEiBYIE 
□DIM  PfllHiBYTE 
□LENGTH=25 

□OPEN  iPATH,"te5t1":UPDflT£(«  open  the  file. 

□LOOP 

□INPUT  "Line  number  to  display, , .".SEEKLINE  (•  type  record  to  find. 

□EXITIF  SEEKLINE>1B  OR  SEEKL1NE<1  THEN  (•  test  if  valid  number, 

OTOIT  (•  exit  loop  if  not 

□SEEK  lPflTH,(SEEKLINE-1)«LENGTH  (•  find  the  requested  record. 

□GET  #PflTH,LlNE  (•  get  the  data. 

□PRINT  LINE  t«  print  the  record. 

□PRINT 

OINPUT  "Type  new  line...  ''.LINE  {•  type  a  new  line. 

□SEEK  #PATH,(SEEKLINE-1)«LENGTH  (•  find  beginning  of  the  record. 

□PUT  fPATH.LlNE  («  store  the  new  line. 

□ENDLDOP  do  it  all  again. 

□PRINT  "That's  all    "      (<  terminate  procedure. 

□CLOSE  IPATH  (•  close  path. 

□END 

This  time,  the  file  is  opened  in  the  UPDATE  mode  to  allow  both 

reading  and  writing.  You  type  the  line  you  want  to  display.  A 
prompt  then  asks  you  to  type  a  new  line.  The  procedure 
exchanges  the  new  line  for  the  original  line,  and  stares  it  back  in 
the  file. 

Using  Arrays  With  Baadom  Accesi  Files 

BASIC09's  random  access  filing  system  is  evesn  more  impressive 
when  used  with  data  structures,  such  as  arrays.  Instead  of  using 

a  loop  to  store  the  10  lines  of  the  Random  replace  procedure, 

you  could  store  them  all  at  once,  into  one  record,  using  an  arr^. 
The  following  procedure  illustrates  this: 
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PROCEDURE  arraywrite 

DDIM  LINEiSTRING[251 
ODIM  REC0RD(1B);STRING[251 
ODIM  PATH;BYTE 
DLENGTH=25 


OON  ERROR  GOTO  10 
□DELETE  "test!" 
UaON  ERROR 


(«  delete  Testl  if  it  exists. 


DCREATE  #PflTH,"tast1«!!ilRITE 
DBASE  I 


(*  tmU  Testf. 


OFQR  T-8  IB  9 
OREAD  RECORD(T) 
□NEXT  T 

□SEEK  tpm,i 
DPUT  IPATH, RECORD 
DClnSf  iPflTH 

□OPEN  #PATH,"te5tl"!.READ, 
□FOR  T=B  TO  9 
□SEEK  fPATH,LEK@TH*T 
□GET  #PflTH,LINE 
□PRINT  LINE 
□NEXT  T 
□CLOSE  #PftTH 
DEfiD 


(»  lead  data  lines  into  REeORB  array. 


(*  set  pointer  to  beginning  of  file. 

(•  store  the  entire  arrty  into  file. 

(«  close  path  to  file. 

(,»  open  the  file  to  read. 

(*  find  each  elemeTit. 

(•  read  an  element , 

(♦  print  the  element. 


□DATA 


aiATA 
□DflTfl 

□DATA 
□DATA 


DBATA 
□DATA 
□DATA 


"This 
mis 
"This 
"This 
"This 
"This 
«fh«5 
"This 
"This 
"This 


is  test 
is  test 
is  test 

is  test 

is  test 
is  test 

If  16*! 

is  test 
is  test 
is  test 


line  *1" 
line.:*?'' 
line  if 
line  *4" 
line  #5" 
line  *6" 
line  #7'' 
line  *8" 
line  #9" 
line  *ir 
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This  procedure  reads  the  10  hnes  into  an  array  named  Records. 
Then  It  places  the  entire  array  in  tlie  1fe§tl  file,  using  mt  FUT 
statement.  To  show  that  the  structure  of  the  file  is  still  the 
same,  the  original  FOR/NEXT  loop  reads  the  lines,  one  at  a 
time,  and  displays  them. 

Notice  that,  because  you  need  to  write  only  one  element,  you  can 
set  the  iile  pointer  to  0  (seek  #PATH,0).  You  can  rewind  a  file 
polnte  (set  it  to  0)  at  any  time  in  this  fflalMier. 

Yaa  could  save  additional  programming  space  by  alsO  reading  the 
10  lines  back  into  memory  as  an  array.  The  following  procedure 
uses  a  new  array,  Readlines,  to  call  the  file  back  into  memory, 
and  displays  the  lines. 

arraycead 

□BASE  i 

□D I  (1  READLi  mmm  mmmm 

DDIM  FATNiBYTE 

DOPCT  #PATH,"te5t1";R£Ail  P  iSftn  ftie, 

□GET  #PATH, READLINES  {•  read  file  into  array, 

□CLOSE  #PATH 

□FOR  1-i  TO  9 

DPRfNT  READLINES(T)  (•  print  each  elEment  of  the  array. 

□NEXT  T 

□END 

Using  Complex  Data  Struetures 

In  the  previous  section,  yott  stored  and  retrieved  elemea^  ©f  an 
array  that  were  all  the  same  size,  25  characters.  Often  you  need 
to  store  elements  of  varying  sizes,  such  as  when  you  create  a 
data  base  program  with  several  fields  in  caie  record. 

The  following  examples  create  a  simple  inventory  system  that 
requires  a  random  access  file  having  100  records.  Each  record 
includes  the  name  of  the  item  (a  25-byte  string),  the  item's  list 
price  and  cost  (both  real  numbers),  and  the  quantity  on  hand  Can 
integer). 
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First,  you  use  the  TYPE  command  to  define  a  new  data  type 
that  describe  such  a  record.  Ibr  emmpte: 

TYPE  rNV_rTEM«NftME:  STRING [ 25]  ;LIST,CQST:  REAL; 
QTY: INTEGER 

Although  this  statement  describes  a  new  record  type  called 

Inv  item,  it  does  not  assign  variable  storage  for  the  record.  The 

next  step  is  to  create  two  data  structures:  an  array  of  100  rec- 
ords of  type  Inv_item  named  Inv__array  and  a  working  record 
nani6'd 

Wsk-JBm.  l%te  Mlowing  lines  do  1Mb: 

DIM  INV_ARRfiY(1  00)  :  INV_ITEM 
DIM  WDRK_REC  :  INV_ITEM 

To  determine  the  number  of  bj^es  assigned  for  each  type,  you 
can  use  BASIC09's  SIZE  command.  SIZE  returns  the  number  of 
M»g  assigned  to  any  variable,  array,  or  complex  data  structure. 
1^  example,  the  command  line  5IZE(I«I0RKI_REC>  returns  the 
number  37.  The  command  SIZECINV—ARRAY)  returns  the  num- 
ber 3700  . 

You  can  use  SIZE  with  SEEK  to  position  a  file  pointer  to  a  spe- 
cific record's  address. 

The  following  procedure  creates  a  file  called  Inventory  and 
immediately  initializes  it  with  zeroes  and  null  strings.  Five 
iNHn!'  Itties  then  asik  ytru  a  record  nuteber  and  #ie  data  to 
store  in  each  field  of  the  record.  You  can  fill  any  record  you 

choose,  from  1  through  100. 

When  one  record  is  complete,  the  procedure  uses  PUT  to  store 
the  record.  Then,  it  asks  you  for  a  new  record  number.  If  you 
wish  to  quit,  enter  a  number  either  larger  than  100  or  smaller 
than  1. 

PROCEDURE  Irvertory 

□REM  Create  a  data  type  consisting  of  a  25-character  name  field, 
□REM  a  real  list  price  field,  a  real  cost  field,  and  an  integer 
□REM  quantity  field. 

□TYPE  INV_ITEM*NAME!STR!HGt2Sli  LIST.CQSTiREAL;  QTYi INTEGER 

□DIM  INV__ARRAY(1M)!lNV_ITEM  (•  dimension  an  array  using  new  type. 
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□DIM  WORK_REC;INV_ITEM 

□REM  (»  dimension  a  working  variable  of  the  new  type. 

□DIM  PATH [BYTE 

DDN  ERROR  6DTD  18 
□DELETE  "inventory" 

leOON  ERROR 

□CREATE  #PATH, "inventory"      (•  create  a  file  named  Inventory. 

□WOSIL_REC,NAME="  "  (•  set  all  data  elements  to  null  or  t. 

□W0RK_REC.LIST=8 

□lilDRK_REC.CQST=B 

□WORK_REC.QTY=B 

OFDR  N-1  TD  m 

□PUT  #PATH,WDRK_REC 

□NEXT  H 

□LOOP 

□INPUT  "Secwd  mtef  »MHOM  t»  eiiter  mt^er  of  feceril  to  *rlte. 
□IF  RKiffltl  m  lilflll  THIH    («  ChSBk  if  uttinber  Is  valid. 
□PRINT 

□PRINT  "End  of  SbssIoh"         (»  if  not,  end  session, 

□PRINT 

□CLOSE  #PATH 

□END 

DENDIF 

□INPUT  "Item  name?  ",WORK_REC.NAME  (•  type  data  for  record. 
□INPUT  "Lilt  prtctff  ",  WORK—REG.  LI  ST 

□  INPUT  "Cost  price?  " ,WDRK_REC.COST 

□  INPUT  "Quantity?  " ,WDRK_REC.QTY 

□SEEK  *PfiTH,(RNUM-l)»SIZE(WORK_REC)  ('  find  record. 

□PUT  #PATH,WGRK_REC  (•  write  record  to  file. 

□ENULOOP 

IsE^tee  'tefe  IHFUT  stat^i^is  w^^&mm  sepa- 
rately, but  the  F0T  statement  te&mams  'tibe  ifecord  as  a  whole. 

The  next  procedure  lets  you  read  any  record  in  your  Inventory 
file,  and  displays  that  record.  If  you  ask  for  a  record  you  have  not 
yet  filled  with  meaningfiil  data,  the  display  consists  of  a  null 
string  and  zeroes. 

PROCEDURE  readinv 

□TYPE  INV_ITEM=NAMEiSTRINGI2S]!  LIST.COSTiREAL}  STYilNTEOER 
□DIM  WDRK_RIC:INV_ITEM 
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ODiM  mmm 

QDPEN  #PATH,"INVENTORY";REflD 

□LOOP 

OINPUT  "Record  number  to  display?  ",RNUM 

□IF  mmn  m  mmrm  then 

DPRINT  "End  of  Session" 

DPR  INT 

□CLOSE  #PATH 

DEND 

DENDIF 

DSEEK  #PflTH,(RNUI1-1)'SIZECW0RK_REC,) 
□GET  #PATH,WDRK_REC 

□PRINT      "Item", "List  Price",''eo5t  Price","auantlty" 

DPRINT  "  -   — '  --  

DPRINT  RNUM ,  WORK_REC .  NAME ,  WDRKJEC .  L I  ST ,  WDRK_REC .  COST  ,WORI{_REC .  QTY 

□PRINT 
OEHILOtlP 

□END 

This  procedure  accesses  the  file  one  record  at  a  time.  It  is  not 
necessary  to  do  so.  You  can  read  the  entire  file  into  memory  at 
once  by  dimensioning  an  inventory  array  and  getting  the  whole 
file  into  it: 

□TYPE  INV_ITEM>NAME;STRING[25];  LIST,COST:REflL;  QTY;  INTEGER 

□DIM  rNV_ftRmfie«)!rNf_iTEM 

□SEEK  #PflTHJ      ('rewind  the  fUeO 

□GET  *PflTH,lNV_flRRAY 

The  examples  in  this  section  are  simple,  yet  they  illustrate  the 
combined  power  of  BASIC09  complex  data  structures  and  the 
random  access  file  stat^ents.  They  show  that  a  single  GET  or 
PUT  statem@at;  msi  msm  any  amoimt  of  data,  crpai^ed  in  any 
way  you  want.  Other  ad'mntages  are  of  using  complex  data  struc- 
tures are: 

•  The  procedures  are  self-documenting.  You  can  see  easily 
what  a  procedure  does  because  its  structures  can  have 

descriptive  names. 

•  Execution  is  extremely  fast. 

•  Procedures  are  simple  and  usually  require  fewer  state- 
ments to  per&nn  I/O  functions  than  other  BASICs. 
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•  The  procedures  are  versatile.  By  creating  appropriate 
data  structures,  you  can  read  or  write  almost  any  kind 
of  data  from  any  file,  including  files  created  by  other  pro- 
grams or  languages. 
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Displaying  Text  and  Graphics 


BASIC09  has  three  levels  of  graphics  capabilities.  The  first  and 
thirdl  ImeAs  can  iBeltti^  Itolli  gi-a|thlBS  ieslpas  ani  1^,  The  sec'- 
ond  level  can  display  only  graphi^  designs. 

ASCII  Codes 

For  low-resolution  text  screens  and  high-resolution  text  and 
graphic  screens,  BASIC09  uses  ASCII  (Asaerican  Standscrd  Code 
for  Information  Interchange)  codes  to  represent  the  common 
alphanumeric  characters.  ASCII  is  the  same  code  that  most 
small  computers  xise. 

A  table  of  the  standard  codes  follows: 


Table  9.1 
BASIC09  ASCII  Codes  0-127 
Low-  and  High-Resolution  Screws 


Character 

Decimal  Code 

Hexadeein 

1  BREAK  1 

03 

03 

B 

8 

08 

9 

09 

10 

OA 

1  CLEAR  1 

12 

OC 

1  ENTER  1 

13 

OD 

Space 

32 

20 

r 

33 

21 

« 

34 

22 

# 

35 

23 

$ 

36 

24 

% 

37 

25 

& 

38 

26 

39 

27 

( 

40 

28 

) 

41 

29 

* 

42 

2A 

+ 

43 

2B 

> 

44 

2C 

45 

2D 

46 

2E 

/ 

47 

2F 

0 

48 

30 
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Character  Decimal  Code     Hexadecimal  Code 


1 

49 

31 

2 

50 

32 

3 

51 

33 

4 

52 

34 

5 

53 

m 

6 

54 

36 

7 

55 

37 

8 

56 

38 

9 

57 

39 

: 

58 

3A 

59 

SB 

< 

60 

30 

61 

3D 

> 

62 

3E 

? 

63 

3f 

@ 

64 

40 

A 

65 

41 

B 

66 

42 

C 

67 

43 

D 

68 

44 

E 

69 

45 

F 

70 

46 

G 

71 

47 

H 

72 

48 

I 

73 

49 

J 

74 

4A 

K 

75 

4B 

L 

76 

4C 

M 

77 

4D 

N 

78 

4E 

0 

79 

4F 

P 

80 

50 

Q 

81 

51 

R 

82 

52 

S 

83 

53 

T 

84 

54 

U 

85 

55 

V 

86 

56 

w 

87 

57 

X 

88 

58 

Y 

89 

59 

Z 

90 

5A 

[(ISHlRlltl) 

91 

5B 
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Character  Decimal  Code     Hexadecimal  Code 


\  (LSHIFT 

II  CLEAR  i) 

92 

5C 

]  (1  SHIFT  II 

93 

5D 

94 

5E 

(I  SHIFT 

II  *  1) 

95 

5F 

96 

60 

a 

97 

61 

b 

98 

62 

c 

39 

63 

d 

100 

64 

e 

101 

65 

f 

102 

66 

B 
e 

103 

67 

h 

104 

68 

i 

105 

69 

J 

106 

6A 

k 

107 

6B 

1 

108 

6C 

m 

109 

6D 

n 

110 

6E 

0 

111 

6F 

p 

112 

70 

Q 

113 

71 

r 

114 

72 

s 

115 

73 

t 

116 

74 

u 

117 

f§ 

V 

118 

76 

w 

119 

77 

X 

120 

78 

y 

121 

79 

z 

122 

7A 

{ 

123 

7B 

1 

124 

7C 

} 

125 

7D 

■ 

126 

7E 

127 

7F 

Yoa  can  gMierate  the  characters  in  this  chart  by  pressing  the 
appropriate  key,  or  you  can  generate  them  from  BASIC09  using 
the  CHR$  function. 
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Low-Resolution  Graphic  Characters 

In  addition  to  alphanumeric  characters,  low-resolution  graphics 
also  offers  graphic  characters.  Generate  these  characters  by 

pressing  |  alt  |  at  the  same  time  you  press  a  keyboard  character. 
The  graphics  character  codes  are  in  the  range  128-255. 

Pressing  I  alt  |  while  pressing  another  key,  causes  OS-9  to  add 
128  to  the  A^Sn  vabie  of  the  second  Issy.  (Pbr  the  technieally 
minded,  OS-9  sets  the  high  bit  of  the  character  code.)  Therefore, 
if  you  press  |  alt  |  [a],  you  produce  graphics  character  193.  You  can 
also  generate  graphics  characters  from  BASIC09  using  the 
CHR$  function,  and  you  can  PRINT  them  in  the  same  manner 
as  other  characters. 

Low-level  graphics  characters  fellow  a  pattern  that  repeats  every 
16  characters.  Table  9.2  shows  the  first  set  of  graphic  characters, 
128-143.  Subsequent  characters  produce  the  same  series  of  con- 
figurations but  display  in  different  colors,  as  shown  in  liable  9.3. 

Table  9.2 

Low-Resolution  Graphic  Character  Set 
Character  Code  Character  Code  Character  Code  Character  Code 


128 


132 


136 


140 


129 


133 


137 


141 


130 


134 


138 


142 


131 


135 


139 


143 
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Table  9.3 

Low-Resolution  Graphics  Color  Set 


ASCII  Code       Graphics  Block  Color 


128 

-  143 

Black  and  Green 

144 

-  159 

Black  and  Yellow 

160 

-  175 

Black  and  Blue 

176 

-  191 

Black  and  Red 

192 

-  207 

Black  and  Buff 

208 

-  223 

Black  and  Light  Blue 

224 

-  239 

Black  and  Cyan 

240 

-  254 

Black  and  Orange 

255 

Green 

Within  each  color  set,  you  can  easily  calculate  the  number  for  a 
particular  character.  Pbr  instance,  suppose  you  want  to  print  a 
character  that  has  orange  upper  left  and  lower  right  comers.  Pic- 
ture the  character  divided  into  four  sections,  numbered  as 
fellows: 


lb  calculate  a  charaeiier'  that  has  orange  at  Sections  8  and  1,  add 
the  section  values  to  the  first  value  in  the  orange  group,  240, 
like  this: 

240  +  8  +  1  =  249 

Character  249  is  what  you  want. 

The  following  diagram  shows  how  you  might  block  out  a  large 
letter  O  on  the  screen.  The  Aaded.  portiiffis  of  the  characters  are 
colored.  The  unshaded  portions  are  black.  In  this  case  we  want 
the  colored  portions  to  be  green  (the  same  color  as  the  screen). 
%u  can  do  this  using  the  color  set  128  - 143. 
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8 

4 

8 

4 

00 

4 

Z 

1 

o 
Z 

i 

z 

1 

8 

4 

8 

4 

8 

4 

— 

1 

i 

8 

4 

8 

4 

8 

4 

Z 

1 

1 

1 

8 

4 

8 

4 

8 

4 

2 

1 

2 

1 

2 

1 

8 

4 

8 

4 

8 

4 

2 

1 

2 

1 

2 

1 

Because  Section  1  in  the  upper  left  character  is  to  be  colored, 
add  1  to  the  initial  character  value  of  128.  The  first  character 
value  is  129.  Moving  right,  Sections  2  and  1  are  colored  in  the 
second  character.  Add  3  to  128  to  get  a  second  character  value  of 
131.  Calculate  all  15  characters  in  this  manner. 

You  could  create  a  letter  O  in  a  BASIC09  procedure  by  printing 
each  of  the  five  rows  of  three  characters.  You  could  use  DATA 
lines  to  store  the  ASCII  codes  for  each  character,  then  use  loops 
to  read  and  display  the  characters  they  represent. 

Although  low-level  graphics  is  very  rough,  it  can  be  useful,  and 
it  lets  you  mix  graphics  with  text. 

The  following  procedure  not  only  creates  the  letter  0,  it  adds  the 
letter  S  and  the  number  9  to  display  the  nsaae  of  your  operating 
system. 
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PROCEDURE  059prog 

□DIM  DAT: INTEGER 

□PRINT  CHR$<12) 

□PRINT 

□PRINT 

□PRINT 

□FOR  Z=1   TQ  5 

□PRINT  TflBCIB); 

□FOR  T=1   TO  12 

□READ  DAT 

□PRINT  CHR$CDAT); 

□NEXT  T 

□PRINT 

□NEXT  Z 

□END 

□DATA  129,131  ,130,143,129,131  ,131  ,143,129,131  ,130, 
143 

DD ATA  1 33 , 1 43 , 1 38 , 1 43 , 1 33 , 1 43 , 1 4  3 , 1 43 , i  32 , 1  4  0 , 1 36 , 

1  43 

□DATA  1  33,1  43,1  38,1  43,1  32,1  40,140,1  43,1  31  ,1  31  ,1  30, 
143 

QDATA  133,143,138,143,131  ,131  ,130,143,143,143,138, 
143 

□DATA  1 32 , 1 40 , 1 36 , 1 43 , 1 40 , 1  40 , 1  36 , 1  43 , 1  43 , 1  43 , 1  38, 
143 
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Special  Characters  in  High-Resolution 

High-resolution  graphics  does  not  have  graphic  characters  but  it 
does  have  other  international  and  special  characters.  These  char- 
acters are  represented  by  ASCII  codes  128  through  159  as  shovm 
in  the  following  table: 


Table  9.4 

High-Resolution  Special  Characters 


Hex 

Decimal 

Hex 

Dechns 

Character 

Code 

Code 

Character 

Code 

Code 

c 

80 

128 

6 

90 

144 

ii 

81 

129 

ae 

91 

145 

e 

82 

130 

M 

92 

146 

i 

83 

131 

6 

93 

147 

a 

84 

132 

6 

94 

148 

a 

85 

133 

0 

95 

149 

§i 

m 

134 

<i 

96 

liO 

? 

87 

135 

^ 

97 

151 

e 

88 

136 

0 

98 

152 

e 

89 

137 

6 

99 

153 

e 

8A 

138 

0 

9A 

154 

ii 

8B 

139 

§ 

9B 

155 

i 

80 

140 

£ 

90 

156 

8D 

141 

± 

9D 

157 

A 

A 

8E 

142 

o 

9E 

158 

8F 

143 

/ 

9F 

159 

Medium-Resolution  Graphics 

Pbr  more  sophisticated  graphics  operations,  OS-9  has  built-in 
graphics  interface  modules  that  provide  a  convenient  way  to 
access  the  graphics  and  joystick  functions  of  the  Color  Computer 
3.  The  required  module  for  medium-resolution  graphics  is  named 
GFX.  It  must  be  in  your  execution  directory  or  resident  in  mem- 
ory when  called  by  BASI009. 

You  can  either  install  GFX  in  memory  using  the  LOAD  com- 
mand, or  wait  until  BASIC09  calls  it  for  a  graphics  function. 
Once  loaded,  GFX  resides  in  memory  until  you  remove  it  using 
the  OS-9  UNLINK  command  or  the  BASIC09  KILL  command. 
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GFX  has  a  number  of  functions  that  you  pass  to  it  as  parame- 
ter the  EUN  statement.  Ibr  instance,  Mlffl^siitf  state- 
ment clears  the  current  grajdiics  screen: 

RUN  ©FXC" CLEAR") 

Other  tasks  need  such  parameters  as  position,  color,  and  size. 
The  following  is  a  quick  reference  to  all  of  the  GFX  functions. 
Each  is  explained  in  detail  later: 


Function  Purpose 


Parametears 


ALPHA      Sets  the  screen  to  the 
alpfaaniimeric  mode. 

CIRCLE     Draws  a  circle. 


CLEAR      Clears  the  screen  to  a 
colctt*. 

COLOR       Changes  the  foreground 
and  background  colors. 

GCOLR      Reads  a  pixel's  color. 


GBLOC         Returns  a  video  displagr 

address. 

JOYSTK     Returns  the  joystick 
button  and  X-  and  Y- 
coordinate  status. 

LINE         Draws  a  line. 


MODE         Switches  the  screen 

between  alphanumeric 
and  graphics,  sets  the 
graphics  screen  color. 

MOVE        Positions  the  invisible 
graphics  cursor. 


NotiB. 


Radius,  optional  X-  and 
Y-coordinates,  and  color. 

Optional  color  for  screen. 


Foreground  and 
background  colors. 

Names  of  variables  in 
which  to  store  optional 
X-  and  Y-coordinates. 

None. 


Names  of  variables  in 
which  to  return  the 
values. 

Ending  X-  and  Y- 
coordinates,  optional 
beginning  coordinates, 
optional  color. 

Format,  Color. 


X-  and  Y-coordinates. 


9-9 


BASIC09  Reference 


Function     Purpose  Parameters 

POINT        Moves  graphics  cursor        X-  and  Y-coordinates 
and  sets  a  point.  and  optional  piKel  ccdor. 

QUIT         Returns  screen  to  None, 
alphanumeric  mode. 
Deallocates  graphics 
memory. 


Formats  and  Colors 


In  medium-resolution  graphics,  you  have  a  choice  of  two  formats. 
Format  0  provides  256  horizontal  points  by  192  vertical  points.  In 
this  format,  you  can  have  only  two  colors  on  the  screen  at  a  time. 

Format  1  provides  a  128  by  192  point  screen  and  a  maximum  of 
four  colors  on  the  screen  at  a  time.  OS-9  medium-resolution 
graphics  treats  the  screen  as  if  it  were  a  grid,  with  coordinate 
0,0  at  the  lower  left  corner  as  shown  in  the  following  illustration. 
AH  points  on  the  grid  are  positive. 


Y-coordinate,0  - 


I  i  I  1  I  1  I  1  I  I  I 
Q,  X-^coordinate 


I   I  I  I 


BASIC09  defines  colors  with  numbers  m  eahr  codes.  Many  GFX 
functions  allow  or  require  color  codes  as  parameters.  BASIC 09 
also  divides  the  color  codes  into  cohr  sets.  Specifying  a  color  code 
outside  the  current  color  set  automatically  initializes  the  new 
set. 
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Color 
Set 


Color 
Code 

Format  0 

Back- 
ground 

Fore- 
ground 

00 
01 
02 
03 

Black 

Black 

04 
05 
06 
07 

Black 

Black 

RnfF 

Format  1 

Color 
Code 

Back- 
ground 

Fore- 
ground 

00 

Green 

Green 

01 

Green 

1  fWHT 
JLcliUW 

02 

Green 

Blue 

03 

Green 

Red 

04 

Buff 

Buff 

05 

Ruff 

06 

Buff 

Magenta 

07 

Buff 

Orange 

08 

Black 

Black 

09 

Black 

10 

Black 

Md  Green 

11 

Black 

Lt  Green 

12 

Black 

Black 

13 

Black 

Green 

14 

Black 

Red 

15 

Black 

Buff 

Table  9^ 

Use  the  preceding  charts  to  chose  colors  for  those  functions  that 
let  you  specify  foreground  or  background  colors.  Ear  instance,  to 
initialize  a  Format  1  graphics  screen  with  a  green  background 
and  a  red  foreground,  you  type: 

run  gfxCtnode'M  ,3) 

The  following  reference  section  describes  all  the  medium-resolu- 
tion graphics  functions,  and  provides  examples  and  sample  pro- 
grams. To  understmni  the  orgaaizatieja  ©f  the  commands 
reference,  see  "The  Syntax  Line"  in  Chaptsr  11. 


9-11 


BASIC09  Reference 


The  Draw  Pointer 

Medium-resolution  graphics  uses  a  draw  pointer,  or  invisible 
graphics  cursor,  to  determine  ^ittefc  area  of  the  screen  is  a£fe@t6d 
by  graphics  operations.  When  you  establish  a  graphics  screen, 
the  draw  pointer  is  located  at  coordinates  0,0.  Some  graphic 
functions  automatically  change  the  pointer  location  on  the 
screen.  For  instance,  the  LINE  function  moves  the  draw  pointer 
from  the  beginning  coordinates  to  the  end  coordinates. 

Because  some  functions  begin  at  the  draw  pointer,  you  need  to 
keep  track  of  its  location  and  make  certain  it  is  placed  properly. 
Use  the  MOVE  function  to  set  the  draw  pointer  to  new  locations. 
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ALPHA  Select  alphanumeric  screen 


Syntax:     MJN  0FX(**ALPHA") 


Function:  Switches  from  the  graphics  screen  t@  'ibe  alpbarai' 
meric  (text)  screen.  The  current  graphics  screen  remains 
intact. 

Parameters:  None 

Examples: 

RUN  GFXC'ALPHA") 

Sample  Program: 

This  procedure  lets  you  choose  to  draw  a  circle  or  rectangle  of 
the  size  you  select.  Once  you  choose  the  shape  and  size,  it  uses 
the  MODE  function  to  select  a  graphics  sereen.  When  the  shape 
is  complete,  you  press  |  enter  |  to  retiim  to  a  teacfc  serem.  Hie  pro- 
cedure uses      ALPHA  function  to  return  to  the  original  menu. 

PROCEDURE  alpha 

□DIM  XC0R,YCDR,SIDE1  , S I DE2 , RAD  I  US , T , X , Y ,Z : INTEGER 
□13 1 M  SESPONSE :  STR I NG  C 1  ] 
10  REPEAT 

□SHELL  "DISPLAY  0C" 

□PRINT  "Do  you   want    to  draw" 

□PRINT  "1 )  A  rectangle" 

□PRINT  "2>  A  circle" 

□PRINT  "       -Press   1   or  2. . ."j 

□GET  #0, RESPONSE 

□PRINT 

OIF  RESP0NSE="1"  THEN 

□INPUT  "Length  of  Side  1...",SIDE1 

□INPUT  "Length  of  Side  2...",SIDE2 

□RUN  GFX("MDDE",0,0) 

□RUN  GFXC"CLEAR"> 

□XC0R=1 0 

□YCDR-10 

□RUN  GFXC"LINE",XC0R,YCQR,XCDR  +  SIDE1 ,YCQR,1  ) 


9-13 


BASIC09  Reference 


DRUN  GFX("LINE",XCDR  +  SIDE1  ,YC0I3,XePR+SIDE1  ,YCDR+ 
SIDE2,1  ) 

DRUN  GFX("LINE",XCDR+SIDE1 , YCDR+S I DE2 , XCDR , YCOR+ 
SIDE2,1  ) 

DRl)  N  ©rt  €  "L  IN  t«» ,  X  CO R ,  YCO  R  +  S I D E  2 ,  X  C  D  R  ,  Y  EpR  *  ^  ) 
DINPUT  RESPONSE 
□  ELSE 

OIF  RESPDNSE="2"  THEN 

DINPUT  "What   radi us ?...", RADI US 

DRUN  GFXC"MODE",0 ,1 ) 

DRUM  GFXC'CLEAR") 

DRUN  GF X C "CIRCLE",!  28,90 , RAD  I  US) 
DINPUT  RESPONSE 
DENDIF 
□END IF 

DUNTIL  RESPDNSEO"!"  AND  RESPDNSE<>''2" 
□RUN  GFX("ALPHA") 
1310TO  10 
□END 
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CIRCLE  Draw  a  circle 


Syntax:     BUK  GFX("CmCLE"[,xcor,ycor\,mdlu8  Ucolor]) 

Function:  Draws  a  circle  of  a  given  radius.  If  you  do  not  spec- 
ify a  color,  BASIC09  uses  the  current  foreground  color.  If  you 
do  not  specify  X-  and  Y-coordinates,  CIRCLE  uses  the  eurrent 
graphics  cursor  position  as  the  circle's  center. 

Parameters: 

radius  The  radius  of  the  circle  you  want  to  draw. 

color  The  code  of  the  color  you  want  the  circle  to  be. 

See  the  chart  earlier  in  this  section  for  color 
information. 

xcor^cor  The  X-  and  Y-coordinates  for  the  center  of  the 
circle.  Specifying  coordinates  outside  the  X- 
coordinate  range  of  0-255  or  outside  the  Y- 
Goordinate  range  of  0-191  causes  an  error. 

Examples: 

RUN  GFXC'C  IRCLE"  ,100) 

RUN  GFXC'CIRCLE" , 1 00 ,3) 

RUN  GFXC'C  I  RCLE"  ,  1  25  ,  1  00  ,  1  00  ) 

RUN  GFXC'C  I  RCLE",  1  25,1  00  ,1  00,2) 

Sample  Program: 

This  procedure  uses  CIRCLE  to  draw  and  erase  a  circle.  The 
location  of  the  circle  changes  before  each  draw/erase  operation, 
causing  the  circle  to  move.  When  it  hits  the  edge  of  the  screen, 
it  reverses  its  direction  at  a  random  angle  and  bounces. 

PROCEDURE  circles 
□DIM  RADIUS, XCOR,YCDR: INTEGER 
□DIM  XTEMP.YTEMP: INTEGER 
□DIM  PATH1 ,PATH2: INTEGER 
□DIM  FLAG! INTEGER 
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DFLAG=1 
DXCDR=5 

DYCDR=5 

0PATH1 =RND(15)+2 
DPATHg^RNDCI 0)+2 
aXTEMF=24t 
DYTEMP=t85 

DRUN  GFXC'MDDE"  ,0,1) 
□RUN  GFXC'CLEAR") 
CFOR  T*t  TO  t08 

□NHILE  XCOR<250  AND  XGDR>4  AND  YCaR<186  AND  YCDR>4 

DQ 

□RUN  GFXC'CIRCLE", XTEMP , YTEMP ,3, 0) 

□RUN  GFXC"CIRCLE",XCDR,YCDR,3,1  ) 

DXTIMP=XCOR 

□YTEMP=YCDR 

□XC0R=XCDR+PATH1 

□YC0R=YCDR+PATH2 

DENDWHILE 

0PATHl«RND«1i>+2 

□PATH2=RND(1 0)+2 

□IF  XCDR>249  THEN 

□XCDR=249 

□ENDIF 

□IF  XC0R<5  THEN 

□XC0R=5 

□ENDIF 

OIF  Y©DR>1&S  THEN 

□YC0R=1 85 
□ENDIF 

□IF  YCOR<S  THEN 

□YCQR=5 

DENDIF 

□FLAG=FLAG»-1 

□IF  FLAG<0  THEN 

□PATH1 =PATH1 •-I 

□PATH2=PATH2«-1 

dENDIF 

□NEXT  T 

□END 
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CLEAR  Clear  the  screen 

Syntam    mm  Gm^^GlMMT'lcolory) 

Function:  Clears  the  current  graphics  screen.  If  you  do  not 
specify  a  color,  CLEAR  sets  the  entire  screen  to  the  current 
backgrounid  cohw.  CLEAR  also  sets  the  graphics  curstHr  at 
coordinates  0,0,  the  lower  left  comer  of  tiie  screen. 

Parameters: 

cohr  A  code  indicating  the  color  to  set  the  screen. 

Examples: 

RUN  GFXC'CLEAR") 
RUN  GFXC'CLEAR", 14) 


9-17 


BASIC09 

COLOR  Change  the  foreground  color 

Syntax:     RUN  GFX("COLOR",coior) 

Function:  Changes  tke  feep-ound  color  (aM  ptxsMUs^  the  color 
set),  COLOR  does  not  chai^  the  graidbics  &rmat  or  the  cur- 
sor position. 

Parameters: 

color  A  code  indicating  the  color  you  want  for  the 

foreground.  See  the  chart  earlier  in  this  chap- 
ter for  color  information. 

Examples: 

RUM  GFXC'CDLOR"  ,  1  0) 

Sample  Program: 

This  procedure  connects  a  series  of  differently  colored  circles  to 

produce  a  necklace  effect. 

PROCEDURE  necklace 

DDIM  COLOR,T,U,J,R,FLAG,XCOR,YGDR: INTEGER 

□RUN  GFXC'MODE'M  ,0) 

□RUN  GFXC'CLEAR") 

□C0L0R=1 

□XC0R=1 

□YC0R»1 

□R=a 

□FDR  T=1   TO  6 

DFDR  J=1    ID  40 

□XCDR=XCDR+1 

□YCDR=YCDR+ .8 

□IF  FLAG<0  THEN 

nR=R-1 

DELSE 

□R=R+1 

□ENDIF 

□C0L0R=CDLDR+1 

□IF  C0LDR>3  THEN  COLOR *1 
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DENDI F 

□RUN  GFXC"CIRCLE",XCOR, YCQR.R.CDLOR) 

□NEXT  J 

□FLAG=FLAG»-1 

□NEXT  T 

□FDR  U=1    TO  10000 

□NEXT  U 

DEND 
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GLOC  Find  tlie  grapMcs  screen  location 


Syntax:    MM  QWXC*mjQC",Btorage) 

Function:  Determines  the  location  of  the  graphics  screen  in 
memory  and  returns  the  address  in  the  specified  variable. 
When  you  know  the  graphic  screen  address,  you  can  use 
PEEK  and  POKE  to  perform  special  functions  not  available  in 
the  GFX  module,  such  as  filling  a  portion  of  the  screen  with  a 
eolor  or  saving  a  graphics  screen  to  disk. 

OS-9  Level  Two  maps  display  screens  into  a  program's 
address  space  before  PEEK  and  POKE  can  operate  on  a  dis- 
play screen.  This  means  that  you  must  have  at  least  eight 
kilobytes  of  free  memory  in  the  user's  address  space.  Program 
and  data  memory  requirements  must  not  exceed  56  kilobytes. 

Parameters: 

storage  An  integer  or  byte  type  variable  in  which 

GLOC  stores  the  memory  address  of  the 
p'SLpbi^  screen. 

Examples: 

RUN  GFXC'GLDC", location) 

Sample  Program: 

This  procedure  uses  the  GLOC  function  to  locate  the  current 
graphics  screen,  then  uses  POKE  to  paint  a  s^ies  of  hoses  on 
th&  screen. 

PROCEDURE  box in 

□DIM  LOCATION .PLACE, CaLOR, BEG  IN, QUIT, X, TERMINATE, 

LINE, T, J: INTEGER 

□  RUN  GFXC'MDDE'M  ,0) 

□RUN  GFXC'CLEAR") 

□RUN  G F X C "GL 0 C " , L 0 C AT I ON ) 

□LDCATI0N=LDGATiaN+1 00  \  PLACE-LDCATIDN 

□BEGIN=1 

DQUIT'80 
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DC0L0R=255 

[]TERMINATE  =  1  0 

□LINE=32 

□FDR   X=1    TO  4 

□FDR  T=1   TO  QUIT 

□FDR  J=BEGIN  TO  TERMINATE 

□PDKE   PLACE+J , COLOR 

□NEXT  J 

OPLACE=PLACE+LINE 
DNEfT  T 

□LOCATIDN=LOCATION+160 

□BEGIN=BEGIN+1 

□PLACE=LOCATION 

□QUIT=QUIT-1 0 

□TERM  I N ATE =TE RMI NATE- 1 

□CDLDR=C0LDR-8S 

□NEXT  X 

□INPUT  Z$ 

□END 
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JOYSTK  Get  joystick  status 


Syntax:     RUN  GFXi"JOYSTK",8tick,are,xcor,ycor) 


FlincM@ni  Determines  the  status  of  the  specified  joystick  fire 
button  and  the  X,Y  position  of  the  specified  joystick  handle. 
Use  this  function  only  wilh  a  standard  joiystick  or  mouse,  not 
with  the  high-resolution  mouse  adapter. 


Parameters: 

stick 

fire 


xcor^cor 


The  joystick  (0  or  1)  for  which  you  want  to 
determine  the  status,  0  indicates  the  right  joy- 
stick, 1  indicates  the  left  joystick. 

A  variable  in  which  JOYSTK  returns  the  sta- 
tus of  the  specified  fire  button.  Fire  can  be 
byte,  integer,  or  Boolean  type.  A  value  other 
than  0  or  TRUE  indicates  the  button  is 


Byte  or  integer  type  variables  in  which 
JOYSTK  stores  the  X-  and  Y-coordinates  of 
the  joystick  handle  position.  The  coordinate 
range  is  0-63. 


Examples: 

RUN  eFX<"JaYSTK",a,shoot ,x,y) 
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This  procedure  uses  the  JOYSTK  fimcticm  to  draw  on  the  screen 

with  the  right  joystick. 

PROCEDURE  joydraw 

DDIM  STICK, FIRE , X C DR , YCQR , XTEMP , YTEMP : INTEGER 

DRUN  GFX{"MODE",0,1  ) 

□RUN  GFXC'CLEAR") 

nJDY=0   \XCOR=0  \YCDR-0 

OREPEAT 

□XTEMP=XCQR 

□YTEMP-YCOR 

□RUN  GFXC"JDYSTK",0,FIRE,XCaR,YCQR) 

□XCDR=XCDR*4 

DYC0R=YC0R»4 

DRUN  GF!j€«l.rME" ,  XTEMP ,  YTEMP ,  XCOR ,  YCOR) 

□UNTIL  FIREO0 

□END 
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LINE  Draw  a  line 

%iitax:    RUN  GWKV'II!m%mml^^Wll,xem^y€i^ 
IcolorJ) 

Function:  Draws  a  line  in  the  current  or  specified  foreground 
edm  in  m&  of  the  following  ways: 

•  From  the  current  draw  position  to  the  specified  X,Y- 
coordinates. 

•  From  the  specified  beginning  X-  and  Y-coordinates  to  the 
specified  ending  X, Y-coordinates. 

Parameters: 

xcorl^corl      Are  LINE'S  beginning  X-  and  Y-coordinates. 

xcor2^cot2      Are  LINE's  ending  X-  and  Y-coordinates. 

color  A  code  indicating  the  color  you  want  the  line 

to  be.  See  the  chart  earlier  in  this  section  for 
color  information. 

Examples: 

RUN  GFX("LINE",192,128) 
RUN  GFXC"L INE" , 0 , 0 , 1 92 , 1 28) 
RUN  GFX("LINE",0,0,192,128,2) 
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Sample  Program: 

This  procedure  draws  a  sine  wave  of  vertical  lines  across  the 
screen. 

PRQ©EDUI?E  waves 

□DIM  A,B,C,D,X,Y,Z;INTEGER 

DCfiLC  =  0   \  Pi  =  100 

DRUM  GFX("mode",0,1 ) 

□RUN  GFXC'CLEAR") 

□RUN  GFX("CaLDR",2J 

□FDR   X=0  TO   2B5  STEP  1 

□CALC=CALC+ . 05 

□Y=A-SINCCALC)«15 

nZ=Y+25 

mun  GF X  t  "L I NE" ,  X , Y ,  X ,  Z ) 

□NEXT  X 
□END 


9-25 


BASIC09  Reference 


MODE  Switch  to  graphics  screen 


Syntax:     RUN  GFX("MODE",foriBai,eoiar) 


Function:  Switches  the  screen  from  alphanumeric  (text)  to 
graphics,  selecting  the  screen  format  and  color  code.  You  must 
run  MODE  before  you  can  use  any  other  graphics  function. 
When  you  do,  BASIC09  allocates  a  six-kilobyte  block  of  mem- 
ory finr  grajSues,  If  your  system  ^es  not  have  this  amoxmt  of 
memory  available,        returns  an  error  message. 

Parameters: 

format  Either  0  (a  two-color  256  Ijy  192  pixel  screea) 

(»:  1  (a  finir-color,  128  by  192  pixel  screen). 

cotor  A  code  indicating  the  color  to  set  the  screen. 

See  the  chart  earlier  in  this  chapter  for  infor- 
mation on  color  sets. 

Examples: 

RUN  GFXCMDDE",  1  ,2) 
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MOVE  Move  graphics  cursor 


Syntax:     RUN  GWXi"MOVE", xcm,yeor) 

Function:  Moves  the  invisible  graphics  cursor  to  the  specified 
location  on  the  screen.  MOVE  does  not  change  the  display  in 
any  way. 

Parameters: 

xcor,ycor  The  coordinates  for  the  cursor. 

Examples: 

RUN  eFXCMOVE"  ,  1 92  , 1  28) 

Sample  Program: 

This  procedure  draws  and  pops  bubbles  on  the  screen  using  the 
CIRCLE  function.  It  uses  MOVE  to  select  the  position  for  the 
circles. 

PROCEDURE  bubbles 

DDIM  XCDR,YCDR,T,R,ARRAY(3, 100): INTEGER 
DRUM  GFXC'MDDE'M  ,0) 
□RUN  GFXC'CLEfiR") 

□FDR  T=1    TD  20 

□  ARRAYCI  ,T)  =  RND(255) 

ZARRAYC2,T)=RND(192) 

DARRAY(3,T)=RNDC50) 

DRUN  GFX("M0VE«,ARRAY(1 ,T3,ftRRAYI2,T)) 
□RUN  GFXC'CIReLE",ARRAYC3,T),3) 

□NEXT  T 

□FOR  T=1    TD  20 

□RUN  GFX("M0VE",ARRAYC1  ,,T),ARRAYC2,T)) 
□RUN  GFXCClReLE",  ARRAY(3,T)  ,0) 
□SHELL  "DISPLAY  07" 

□NEXT  T 
□END 
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POINT  Set  point  to  specified  color 


Syntax:     RUN  GFX("POINT",xeor,j«jor[,coior]) 

Function:  Displays  a  dot  at  the  specified  coordinates.  If  you 
specify  a  color,  POINT  sets  the  pixel  at  the  new  coordinates  to 
that  color.  Otherwise,  POINT  sets  the  pixel  at  the  new  coordi- 
nates to  the  foreground  color. 

Parameters: 

xa>rjcor         The  X-  and  Y-coordinates  for  a  pixel. 

color  The  code  of  the  color  you  want  the  pixel  to  be. 

See  the  chart  earlier  in  this  section  for  color 

Examples: 

RUN  GFX("PDINT",192,128) 
RUN  GFXC"PDINT'M92,128,2) 

Sample  Program: 

This  procedure  uses  POINT  to  draw  filled  boxes  on  the  screen. 

PROCEDURE  boxup 

neiM  XCQR.YCOR, BEGIN, COLOR, QUIT, TERM  I  NATE, LINE: 
INTEGER 

□DIM  T,X ,Y: INTEGER 

□XCDR=50   \YCOR=30  \CDLDR=1 

□BEGIN=1    \START=1    \QUIT=20  \TERM I NATE-S0 

DRUN  GFXC"M0DE",1 ,0) 

DRUN  GFXC"CLEAR") 

OFDR  T=1    TD  4 

□FDR   X=BEGIN  TO  QUIT 

□FDR  Y=START  TO  TERMINATE 

□RUN  GFX<"PDINT",XCOR+Y, YCQR.COLORJ 

□NEXT  y 

□YC0R=YC0R+1 

□NEXT  X 

DSTART=START+1 0 
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QTERMINATE=TERMINATE-1 0 

nC0L0R=CDLDR+1 

□NEXT  T 

□INPUT  Z$ 

□END 
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QUIT  Deallocate  grapMcs  screen 


Syntei    MJH  GFX("QUIT") 

Function:  Switches  the  screen  to  the  alphamuoedc  (text)  mode 
and  deallocates  graphics  memory. 

Parameters:  None 

Examples: 

RUN  GFXC'QUIT") 
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High-Resolution  Graphics 

BASIC09's  high-resolution  graphics  greatly  expand  the  capabili- 
ties of  the  Color  Computer  3.  You  can  have  greater  screen  resolu- 
tion (up  to  640  by  192  pixels),  as  many  as  64  colors,  and  the 
ability  to  mix  graphics  and  text  on  one  screen.  In  addition,  you 
can  use  different  text  fonts,  or  styles. 

The  high-resolution  module,  GFX2,  has  many  more  functions 
than  its  medium  resolution  counterpart.  GFX2  gives  you  the 

ability  to: 

•  Select  from  64  colors.  OS-9  provides  a  palette  with  16 
ds^ult  eolcsi.  Yaa  mm.  change  smy  d  Vbem  diG&mlt  colors  to 
a^  of  liie  @4  colors  available  on  tibe  Color  Computer  3, 

•  ^1  border  colors. 

•  Set  cidor  pitlems. 

•  Ci^eato  diitemt  tj^es  of  p-aphics  screen  cursors. 

•  Use  bgic  functions. 

•  Turn  an  automatic  scaling  function  off  or  on. 

•  Draw  oufline  or  filled  boxes. 

•  Draw  ellipses  and,  ares. 

•  Fill  specified  arKis  with  specified  colors. 

•  GET  and  PUT  sections  of  the  graphics  screen. 

•  Select  character  fonts,  which  include  bold&ced,  transparent, 

and  proportionally  spaced  characters. 

•  Move  the  cursor.  Erase  portions  of  a  line  or  of  the  screen. 

•  Select  reverse  or  normal  video. 

•  Underline  text. 

Also,  high-resolution  graphics  operate  through  the  OS-9  Win- 
dowing System.  This  means  that  you  can  run  several  procedures 
in  different  windows.  You  can  establish  windows  to  display  text, 
or  to  display  graphics,  or  both.  You  can  easily  displsy  any 
window. 
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Establishing  a  Hardware  WindQW 

For  your  convenience,  OS-9  has  a  number  of  predefined  or  hard- 
ware window  formats.  Hardware  windows  are  text  windows,  and 
you  cannot  use  them  for  graphic  applications.  Because  hardware 
wirutows  pedefined,  you  can  easily  establish  them  with  the 
W!M  (snnmand.  'Fbr  instance,  to  eslaMMi  Wiodiim  7,  type: 

Iniz  w7  I  ENTER  I 

However,  you  eaimcii  see  the  wlnS/m  mM  yott  send  a  tftessiqp 
it.  Type: 

echo  Hello  Window  7  >  /w7  | ENTER | 

Now,  to  see  the  window  and  your  message  press  I  CLEAR  |.  lb 
return  to  the  original  screen,  press  |  clear  |  again. 

To  OS-9,  a  window  is  a  device  and  you  can  send  data  to  it.  To 
view  the  Errmsg  file  in  the  SYS  directory  of  your  system 
disbette,  list  it  to  Window  7  by  typing: 

list    sys/errmsg   >    /w7  |  ENTER] 

Press  I  CLEAR  I  to  move  to  Window  7  and  see  the  listing.  Press 
I  SHIFT  II  CLEAR  |  to  retum  to  the  previous  screen. 

You  can  also  fork  a  shell  (an  execution  environment)  to  a  win- 
dow. To  cause  a  shell  to  operate  in  Window  7,  type: 

shell   l  =  /w7&  flffERl 

The  i  =  function  of  SHELL  tells  OS-9  that  the  window  is  im- 
mortal. It  does  not  die  after  completing  a  task.  To  operate  OS-9 
from  the  window,  press  I  ctMR  I. 

Besides  Window  7,  you  have  six  other  predefined  windows.  The 
following  chart  shows  all  the  hardware  windows  and  their 
parameters: 
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oiarting 

C  o  ordinB  tG  s 

A.-L-'OOrClj 

Window  Size 

KjAxaTal  llllc 

Cols 

Rows 

1 

40 

0,0 

27 

11 

2 

40 

28,0 

12 

11 

3 

40 

0,12 

40 

12 

4 

80 

Q,0 

60 

11 

S 

SO 

60,0 

19 

11 

6 

80 

0,13 

80 

12 

7 

80 

0,0 

80 

24 

Defining  Windows 

As  well  as  hardware  windows,  OS-9  also  lets  you  establish  win- 
dows to  your  own  specifications.  Yom  can  set  definable  windows 

for  either  text  or  graphics,  or  both.  You  can  locate  them  any- 
where on  a  screen,  and  you  can  make  them  any  size. 

You  initialize  definable  windows  in  the  same  manner  you  initial- 
ize hardware  ^ttSmta,  using  INIZ.  If  you  want  to  have  tesst  on 
the  window,  you  must  merge  SYS/Stdfonts  (found  on  your  system 
diskette)  with  the  window.  You.  can  also  establish  a  shell  in  a 
definable  window,  from  which  you  can  use  OS-9  or  BASIG09. 

lb  establish  definable  windows  you  must  supply  OS-9  with  infor- 
mation about  the  type  of  window  you  want  (its  graphic  format), 
its  size,  and  its  location  on  the  screen.  Th©  easiest  way  to  do  this 
is  with  the  OS-9  WCREATE  command. 
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WCREATE  requires  a  window  format  code  in  the  form 
-  s=  format  code  to  tell  OS-9  what  type  of  a  window  you  want. 
The  foUovdng  chart  shows  the  possible  window  fi)rmats  you  can 
choose: 

Table  9.6 


Format 

Screen  Size 

Resolution 

No.  of 

Memory 

Screen 

Code 

Cols  X  Rows 

Width/Height 

Colors 

Required 

Type 

01 

40  X  24 

let 

1600 

Text 

02 

80  X  24 

16t 

4000 

Text 

05 

80  X  24 

640  X  192 

2 

16000 

Graphics 

06 

40  X  24 

320  X  192 

4 

16000 

Graphics 

07 

80  X  24 

640  X  192 

4 

32000 

Graphics 

08 

40  X  24 

320  X  192 

16 

32000 

00*    Specifies  the  current  screen. 
FF     Current  display  screen.  Use  when  putting  several  windows  on  the  same 
physical  screen. 

t  Yaa  have  to  reconfigure  the  palette  to  get  16  colors  rather  than  the  default  <^ 
eight  cdars.  The  fidkwiiig  section  pcevides  ii^banation  on  the  palette. 

Format  Codes  01  and  02  select  text  screens,  and  Format  Codes  5- 
8  select  graphics  screens.  The  Screen  Size  column  shows  the 
maximum  number  of  text  columns  and  rows  available  for  each 
screen.  The  Resolution  column  shows  the  maximum  pixels 
(graphic  units)  arailable  each  d£  the  graphic  screens.  The 
Memory  column  shows  how  much  memory  OS-9  must  set  aside 
for  each  screen  format.  Memory  requirements  depend  on  the  res- 
olution and  number  of  colors  sdected  for  a  window. 

The  Palette 

BASIC09  has  64  colors  you  can  select  fijr  screen  displays.  The 
colors  are  available  iJirough  a  palette.  The  Cdor  Computer's  pal- 
ette can  hold  16  colors  at  once. 


9-34 


Displaying  Text  and  Graphics  I  9 


The  following  chart  shows  the  default  colors  for  the  palette  in 
Screen  Ibrmat  7: 

T^ble  9.7 


Register 

Color 

Register 

Color 

00 

Black 

08 

Black 

01 

Red 

09 

Green 

02 

Green 

10 

Black 

03 

Yellow 

11 

Buff 

04 

Blue 

12 

Black 

05 

Magenta 

13 

Green 

06 

Q^an 

14 

Ma^ 

07 

White 

15 

Orange 

Instead  of  the  default  colors,  you  can  select  any  of  the  64  colors 
(0-63)  for  any  of  the  palette  registers.  You  do  this  using  the  PAL- 
ETTS5  conimand  described  latet  in  this  chapter.  Vt^  BORDER 
and  COLOR  commands  also  affect  the  colors  available  in  the  pal- 
ette by  changing  the  color  in  the  background  and  foreground 
registers,  Registers  02  and  03,  respectively. 

Note:  The  information  in  the  next  section  assumes  JiOU  haW6 
a  Color  Computer  3  with  512  kilobytes  of  memory.  If  your 
computer  has  128  kilobytes  of  memory,  skip  to  the  section 
"ffigh-Level  Graphics  With  128K." 

Establishing  a  Graphics  Window 

To  create  any  window,  you  should  first  initialize  it  with  the  INIZ 
command.  I^P©: 

iniz  w1  I  ENTER  | 

So  that  y#u  can  later  type  in  the  new  window,  merge  the 
Std&nts  file  with  it.  Type: 

merge  sys/stdf  onts>/w1  |  ENTER  I 

Using  the  information  in  the  preceding  tables,  use  WCREATE  to 
establish  a  graphics  window.  The  following  command  line  creates 
a  graphics  window  in  Window  1  that  has  320  x  192  resolution 
and  that  fills  the  entire  screen.  The  new  window  has  16  colors 
available  and  pt^des  40  cohimn  1^  14  line  text: 
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wcreate  /w1  -5  =  8  00  00  40  24  03  02  02  |  ENTER  | 

ThiB  ispien  border  color 

I  >  The  ae^mo.  Imxhgi^misi. 

color 

I  >  The  screm  foreground 

color 

I  ^  The  screen  length  in 

rows 

I  ^  The  screen  width  in 

columns 

I  ^  The  Y-Coordinate  for  the 

beginning  of  the  screen 

I  ^  The  X-coordinate  for  the 

begiiming  of  the  screen 

I  >  The  screen  type 

I  The  window  name 

 ^  The  command  name 

Starting  a  Shell  in  a  Window 

At  this  point,  the  new  window  exists,  and  you  can  send  data  to 
it.  However,  if  you  want  to  operate  from  the  window,  you  must 
install  a  shell  in  it.  Type: 

shell   i°/w1  >  lEMTERI 

Frms  I  CLEAR  I  to  move  to  the  new  window.  To  load  BASIC09,  type: 

bag  i  c  0  9  #1  0  K  |  ENTER  | 

Select  either  more  or  less  memory,  according  to  your  needs. 
Using  BASIC09  in  a  graphics  window,  you  can  write  procedures 
to  create  high-resolution  graphics,  and  you  can  display  the 
graphics  on  the  same  screen. 
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Using  High-Level  Graphics  With  128K 

If  your  computer  is  equipped  with  only  128  kilobytes  of  memory, 
you  cannot  use  more  than  one  window  with  BASIC09.  Also,  to 
use  even  one  window,  you  must  follow  certain  steps  to  provide 
enough  memory  for  BASIC09  operations. 

Refer  to  Table  9.6.  You  must  select  a  window  mode  that  does  not 
use  more  than  16000  byte  of  memory — either  window  Format  5 
or  Ebrmat  6. 

To  provide  enough  memory  to  use  BASIC09,  you  must  fork  a 
shell  to  the  window  you  create,  then  kill  the  shell  in  TERM. 
Doing  this  means  that  you  can  no  longer  operate  from  your 
TERM  screen.  However,  you  can  run  OS-9  and  BASIG09  from 

the  window. 

The  following  steps  show  you  how  to  create  a  Format  6  graphics 
screen  in  Window  1,  write  a  BASIC09  high-resolution  graphics 
procedure,  and  execute  it  using  minimum  memory. 

1.  Boot  OS-9.  Then,  create  a  graphics  window  by  typing: 

iniz   w1  I  ENTER  | 

wcreate   /w1    -5  =  0G  BB   00   40   24   0G  01    01  |  ENTER  | 
merge   5y s  /  s  t  d f  on  t  5  > /w1   |  ENTER  | 
shel  1    i  =  /w1  4  |  ENTER  | 

ex  I  ENTER  | 

2.  The  system  stops,  and  you  CMt  no  .longer  type  W  iiiUljft  eOHS- 
mands.  Press  |  clear  |  to  move  to  the  new  window.  Thm,  load 
BASIC09  by  typing: 

ba5ic09  I  ENTER  | 

3.  Enter  the  edit  mode,  and  type  the  following  procedure: 

PROCEDURE  squeeze 

□DIM   XCDR,YCDR,X,Y: INTEGER;   RESPONSE : STR I  NO [ 1  ] 
DRUN  GFXSC'CURQFF") 

DTCOR=3f0  \  YeOR=9S  \  |=ff0  \  FL*t»1 

□PRINT  CHR«C12> 

□LOOP 

□FDR  Y=1  TO  100  STEP  2 

0X.-X-3 

OGaiffUB  10 

□IF  FLAG<1  THEN 

□RUN  GFX2C"CDLDR",0) 
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DELSE 

□RUN  GFX2("C0LQR" , 3) 
□ENDIF 

PRUN  GFX2("ELLIPSE",XC0R, YCDR.X,  Y) 
DFLAG=FLAG*-1 

DNEXT  Y 

□RUN  GFX2C"CQLDR",1 3 
□FOR  Y=99  TO  1   STEP  -2 
□CDSUB  10 
OX-X+3 

□RUN  GFX2<"ELLIPSE",XC0R,YC0R,X,Y) 

□NEXT  Y 

QRUN  GFX2C"CDLOR",0J 
QENDLDDP 

10ORUN  INKEY(RESPDNSE) 
□IF  RESPONSE-""  THEN 
□RETURN 
□END IF 

10DPRINT  CHR$(12) 
□RUN  GFX2("C0L0R" , 0> 
□RUN  GFX2t"CURDN"> 

□END 

4.  When  you  have  entered  the  procedure  exaetly  as  shown,  eadt 
the  edit  raoig,  md  £rom  1^  enmod  mode,  ssm 
Squeeze  1^  typinf: 

aa:¥6  squeeze  I  @gEH  I 

5.  Compile  Squeeze  Isy  lining: 

pack  squeeze  I  ENTER! 

Squeeze  is  now  an  executable  module  saved  in  your  current 
execution  directory.  The  following  steps  assume  your  execu- 
tion directory  is  /DO/CMDS. 

6.  Exit  BASIC09  l^y  lypii^. 

bye  I  ENTER  | 

7.  Merge  Squeeze,  RUNB,  INKEY,  and  GFX2  into  one  module. 

To  do  this,  type: 

merge  /d0/cmd5/5queeze  /d0/cmd5/runb  /d0/cmds/ 
inkey  gfx2  >  /dB/cmds/yawn  lENTiBlf 
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8.  MERGE  does  not  set  the  new  file  Yawn  as  an  executable  file. 
Before  you  execute  it,  you  must  make  the  file  executable  by 
typing: 

attr  /d0/yawTi  e  pe  |  ENTER  | 

9.  lb  esecute  "Sawn,  type: 

yawn  |  ENTER  | 

10.  To  terminate  the  procedure,  press  the  space  bar. 

The  merging  procedure  in  Step  7  saves  a  considerable  amount  of 
memory.  Every  module  you  load  uses  one  or  more  8-kilobyte 
blocks  of  storage  space.  Fbr  instance,  INKEY  is  only  94  b3H;es  in 

length.  However,  if  you  load  it  as  a  separate  module,  it  requires 
8192  bytes.  RUNB  is  12185  bytes  in  length.  This  means  that  it 
requires  two  8-kilobyte  blocks,  or  16384  bytes  of  memory.  GFX2 
is  2190  bytes  in  length,  and  Squeeze  is  605  bytes  in  length. 
Loaded  individually,  they  also  require  two  memory  blocks. 

If  you  load  all  four  modules  independently,  they  use  40080  bytes. 
However,  by  combining  them  into  one  file,  they  load  into  two 

memory  blocks,  or  16384  bytes. 

Using  the  information  in  this  section,  you  can  write  and  execute 
numerous  BASIC09  procedures  with  only  128  kilobytes  of  mem- 
ory. However,  if  your  computer  has  512  kilobytes  of  memory,  you 
can  bypass  many  of  these  steps.  Also,  the  additional  memory 
enables  you  to  have  several  windows  open  at  one  time.  For 
instance,  you  can  create  one  window  in  which  to  write  BASIC09 
procedures,  another  window  in  which  to  ^cecute  your  procedures, 
and  a  third  window  firom  which  you  can  xtm  OS-9  c^omsHids. 

Note:  The  remainder  of  this  chapter  assumes  you  have  512 
kilobytes  of  memory.  If  you  don't,  you  can  still  run  many  of 
the  sample  procediires  1^  implementiz^  the  steps  in  this 
section. 


Using  <WK2  routines,  BMI009  pm^m  the  tmam  to  ^^te 
and  manage  windows.  The  steps  for  creating  windows  from 

BASIC09  are  as  follows: 

1.  DIM  a  variable  to  hold  the  path  number  to  the  window  you 
want  to  create. 


Windows  from  BASIC09 
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2.  OPEN  a  path  to  the  window. 

3.  SELECT  the  new  window  as  the  display  window. 

4.  Send  commands,  data,  or  text  to  the  window  through  the  open 
path. 

5.  CLOSE  the  open  path. 

6.  Use  SELECT  to  return  to  your  original  window. 

If  you  do  not  want  to  return  immediately  to  the  screen  or 
dow  of  origin,  you  can  skip  Steps  S  and  S. 

The  following  sample  procedure  shows  how  to  open  Window  2  as 
a  320  X  192  graphics  window,  draw  a  circle,  then  retxirn  to  the 
original  swsm  vksm  fou  jsress  a  key. 

PROCEDURE  make_win 
DIM  PATH: INTEGER 
DIM  RESP0NSE:STRING[1  ] 
□PEN  #PATH ,"/N2" :WRITE 

RUN  GFX2  (PATH, "DWSET", 08, 00, 00, 40, 24, 03, 02, 02) 

RUN  GFX2  CPATH, "SELECT") 

RUN  GFX2  (PATH, "CIRCLE", 200, 90, 80) 

GET  #1 .RESPONSE 

CLOSE  #PATH 

RUN  GFX2  ("SELECT") 

END 

This  procedure  e&babfi^es  a  fbniiai  8  window,  he^tittinf  at 
Coordinates  0,0  and  covering  the  total  screen.  The  foreground 
color  is  green,  the  background  color  is  black,  and  the  border  color 
is  black. 

Because  this  procedure  does  not  INIZ  the  window  it  opens,  the 
window  automatically  disappears  when  the  procedure  closes  its 
path.  To  create  a  window  that  stays  in  the  system,  even  after 
you  close  the  path  to  it,  use  INIZ  before  the  OPEN  statement, 
like  this: 

SHELL   "INIZ  /N2" 

After  you  create  and  define  the  window,  view  it  by  pressing 
I  CLEAR  |.  To  get  back  to  the  screen  you  are  working  on,  press  |  shift  | 
I  CLEAR  |.  If  you  intend  to  use  a  window  more  than  once  in  a  proce- 
dure, you  do  not  need  to  close  its  |wth  until  ^mm^bam  no 
longer  needs  it. 
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Creating  Overlay  Windows 

When  you  establish  a  window,  you  are  initializing  an  OS-9 
dewice.  However,  an  overlay  window  is  only  a  new  scretsti  for  an 
existing  window.  An  overlay  screen  can  be  the  same  size  as  its 
window,  or  it  can  be  smaller.  OS-9  automatically  transfers  to  the 
overlay  window  any  current  procedures  operatii^  in  the  device 
window. 

The  process  for  creating  overlay  windows  lets  you  select  whether 
you  want  to  save  the  contents  of  the  scr®Mi  em&mi.  the  mm 
window.  If  you  choose  to  save  the  contents,  the  previous  screen  is 
redisplayed  when  you  end  the  overlay. 

The  following  procedure  provides  an  example  of  using  overlay 
windows.  It  creates  six  overlays,  each  smaller  than  the  preceding 
window.  The  procedure  then  waits  for  you  to  press  a  key.  When 
you  do,  it  xmxmm  fte  overlay  Win&ws. 


PROCEDURE  overwlndows 

□DIM  X,Y,X1  ,Y1  ,T,J,B,L,PLACE:INTEGER 

□DIM  RESPQNSE:STRING[1 ] 

□X-8  \Y-0 

□XI -80  \Y1=24 

□PLACE=33 

□FOR  T=1    TO  e 

□IF  T=2  OR  T=6  THEN 

□B=3 

DELSE  B-2 
□ENDIF 

□RUN  GFX2("DWSET'M  , X . Y , XI , Y1  , B , T) 
□X=X+e  \Y=Y+2 
DX1=X1-1g  \Y1=Y1-4 

□FOR   J-1    TO  5 

□PRINT  TABCPLACE);    "Overlay  Screen   ";  T 

□NEXT  J 

□PLACE=PLACE-G 
□NEXT  T 

□PRINT   "Overlay   Screen  6" 

□PRINT  "Press   A  Key. . ."; 

□GET  #1  ,  RESPONSE 

□FOR  T=1   TO  6 

□RUN  GFX2("DW£ND") 

□NEXT  T 

□END 
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The  Graphics  Cursor  and  the 
Draw  Pointer 

High-resolution  graphics  provide  a  text  cursor,  a  graphics  cursor, 
and  a  draiv  pointer.  The  text  cursor  and  the  graphics  cursor  can 
be  either  visible  or  invisible.  The  draw  pointer  is  always 
invisible. 

Text  functions  always  begin  at  the  current  location  of  the  text 
cursor.  Whenever  you  print  on  the  screen,  the  cursor  automati- 
cally moves  to  the  end  of  the  text  or  to  the  beginning  of  the  next 
line,  depending  on  whether  op  not  yoa  use  a  semtewn  afte  the 
print  statement.  You  can  reset  the  text  cursor  to  any  place  on 
the  screen  with  the  CURXY  function  of  GFX2. 

Many  BASIC09  graphics  functions  also  begin  operating  at  a 
location  pointed  to  by  the  draw  pointer.  When  you  begin  graph- 
ics, the  draw  pointer  is  located  at  coordinates  0,0.  BASIC09  thm 
updaties  the  pointer  as  you  execute  certain  graphics  ftmcttons. 
For  instance,  the  LINE  function  of  GFX2  draws  from  the  draw 
pointer  position  to  the  specified  end  coordinates.  The  draw 
pointer  is  left  pointing  to  the  end  coordinates. 

Because  some  functions  begin  at  the  draw  pointer,  you  need  to 
keep  track  of  its  location  and  make  certain  it  is  placed  properly. 
Use  the  SETDPTR  function  to  move  the  draw  pointer  to  new 
bcations. 

The  graphics  cursor  is  for  use  with  joystick  or  mouse  operations. 
It  provides  a  pointer  for  graphics  applications.  The  system 
didsette  provides  patterns  that  can  be  loaded  into  the  graphics 
cursor  buffer.  Yon  can  sdect  from  a  variety  of  pointer  images. 

High-Resolution  Text 

When  you  create  a  graphics  window,  you  can  display  either  text 
characters,  graphics  characters,  or  both. 

lb  display  graphics,  move  the  draw  pointer  to  the  location  where 
you  want  the  graphics  to  begin.  Then,  execute  the  graphics 
routines. 

Tb  displfQT^  ti^,  move  the  text  cursor  to  the  location  where  you 
want  the  text  to  begin.  Then,  use  normal  BASC  commands  to 

print  text. 
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Instructions  for  the  draw  pointer  relate  to  a  640  x  192  grid, 
numbered  0-639  and  0-191.  Instructiom  for  the  fsamm 
relate  to  the  number  of  characters  per  line  and  the  number  of 
lines  on  the  current  screen  format. 

Using  Fonts 

OS-9  has  built-in  fonts  (character  sets).  You  can  also  create  f&wc 
own  fonts  and  instruct  BASIC09  to  use  them.  If  you  create  your 
own  fonts,  you  can  design  any  symbols  or  graphics  characters 
you  want  to  use. 

To  use  fonts,  you  must  be  in  a  graphics  window.  See  "Establish- 
ing a  Graphics  Screen"  earlier  in  this  chapter.  Use  the  FONT 
ftuiction  to  tell  OS-9  what  font  you  want.  BASIC09  has  three 
fonts  installed  in  Group  200,  Buffers  1,  2,  and  3.  The  following 
procedure  uses  characters  in  Buffer  3  to  draw  a  border,  then 
prints  a  message  using  the  characters  in  Buffer  2.  It  then 
returns  to  Buffer  3  and  asks  you  to  press  a  key  to  end  the 
procedure, 

PROCEDURE  borders 

DDIM  T,B,V, J,K: INTEGER 
□DIM  RESPDNSErSTRINGCI ] 
GB=1 99 

□PRINT  CHR$(12) 

□RUN  GFX2C"FONT'S2B0,3) 

□RUN  GFX2("CDLDR", 1 ,2) 

□FOR  T=0   TD  79 

□PRINT  CHR*<B3; 

QHEXT  T 

DFDR  T=1  TO  21 

□RUN  GFX2("CURXY" , 0 ,T) 

□PRINT  CHR$(B);  CHR$CB); 

□RUN  GFXtC«i0tXy"»7t,T> 

DPRIMT  CHR*<B);  CHR$<B); 

□NEXT  T 

□RUN  GFX2{"CURXY",0,21 ) 
□FOR  T=0  TD  79 
□PRINT  OHR$CB)! 
□NEXT  T 

□RUN  GFX2("FONT",200 ,2) 
IRUN  GrX2("CDLDR",0 ,2) 
HRUN  GFX2("CURXY" ,45 ,9J 
□PRINT  "A  Demonstration" 
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ORUN  GFX2C"CURXY",S0 ,1  0) 
□PRINT  "Df  A" 
ORUN  GFX2C"CURXY",43,11  ) 
□PRINT  "Buffer  Three  Border" 
□  RUN  GFX2("CURXY",51,  ,1  2) 
□PRINT  "And" 

t3l?UN  GFX2C  "OUfX Y** ,  ^ S  ,  1  3  > 
□PRINT  "Buffer  Two  Text" 
□RUN  GFX2("FDNT", 200,1 ) 
□RUN  GFX2("C0L0R",3,2) 
□RUN  GFX2("CURXY",33,15) 
□PRINT  "Press  fi  Key. . ."; 
□GET  #1  , RESPONSE 
□PRINT  CHR$(12) 
□END 

High^Eejiolutiiixi  Quick  Refer^ce 

High-resolution  functions  are  all  part  of  the  GFX2  module.  You 
eall  them  in  a  BASIC09  procedure  with  the  following  syntax: 

RUN  GFX2([PflrH]  /' FUHCT I  OH" [ ,PftRftMETERi  ,...]]) 

Path  is  an  optional  variable  name  that  tells  OS-9  the  window  in 
which  you  want  the  function  performed.  Function  is  the  high- 
resolution  task  you  want  to  perform.  Parameter  is  an  essential  or 
optional  value  that  affects  the  performance  of  the  function.  Dif- 
ferent functions  require  or  permit  different  numbers  of 
parameters. 

The  following  reference  gives  a  brief  description  of  the  high- 
resolution  graphics  functioffli.  This  list  is  organized.  l>f  function. 
Pbllowing  the  quick  refermce  is  a  detailed  reference  organized 
alphabetically. 
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Window  Commands 


Cottimand 


Function 


DWSet 


OWSet 


OWEnd 
Select 
DWEnd 
CWArea 

DWProtectSw 


Establishes  a  window  and  sets  its  location 
on  the  screen,  its  size,  its  background  color, 
its  foreground  color,  and  its  border  color. 

Establishes  an  overlay  window  on  a  device 
window  that  already  exists.  The  function 
also  sets  the  overlay  window  size,  back- 
ground color,  foreground  color,  and  border 
color.  When  using  this  function,  you  can 
choose  whether  or  not  to  save  the  contents 
of  the  original  screen. 

Deallocates  the  specified  overlay  window. 

Selects  the  window  to  display. 

Deallocates  an  established  window. 

Changes  the  size  of  a  window.  You  can  only 
reduce  the  working  area  of  a  window,  not 
increase  it. 

Lets  you  unprotect  a  window  and  set  other 
device  windows  over  it.  This  might  destroy 
the  contents  of  either  or  both  windows. 
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Drawing  Commands: 


V/ oniinaiiGi 

r  unction 

Point 

Sets  the  pixel  under  the  draw  pointer  to  the 

specified  color  or  to  the  d^ult  color. 

Line 

Draws  a  line. 

jsox 

Draws  a  rectangle  outline. 

Bar 

Draws  a  filled  rectangle. 

Circle 

Draws  a  circle. 

Ellipse 

Draws  an  ellipse. 

Arc 

Draws  an  arc. 

Fffl 

Fills  the  area  of  the  window  the  same  color 

as  the  pixel  under  the  draw  painter. 

Clear 

Clears  the  window. 
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Configurmg  Commands: 


Command 


Function 


Color 

DrfCol 
Border 
Palette 
Patten 

Logic 

GCSet 

ScaleSw 
SetDPtr 
PutGC 
Draw 


Sets  any  of  the  foreground,  background,  or 
border  colors. 

Sets  palette  registers  to  the  default  colors. 

Sets  the  border  palette  register. 

Changes  colors  in  the  palette  registers. 

Establidies  a  bufTer  from  which  BASIC09 
gets  a  pattern  for  graphics  functions. 

Turns  on  AND,  OR,  or  XOR  logic  functions 

for  draw  functions. 

Establishes  a  buffer  from  which  BASIC09 
gets  the  graphics  cursor. 

Turns  sealing  on  or  off. 

Positions  the  draw  points. 

Positions  the  graphics  cursor. 

Draws  an  image  from  directions  provided  in 
a  draw  string. 


Command  Ftmction  

Get  Saves  a  specified  portion  c£  a  window  to  a 

buffer. 

Put  Places  the  image  stored  in  a  buffer  onto  a 

window. 

DefButi  Defines  a  buffer  for  storage. 

GPLoad  Preloads  a  buffer  from  a  disk  file. 
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Tl^t/Cursor  Handling  Routines: 

Command  Function  

CurHome  Positions  the  cursor  at  coordinates  0,0. 

CurXY  Positions    the    cursor    at  specified 

Etrlins  Erases  ft@  Hue  unie?  Hi©  «!tti^> 

IkSOtiixe  Bmses  from  #ie  mxmr  to  the  end  of  Ihe 
line. 

CiirOff  Turns  the  graphics  cursor  off. 

CurOn  TuEtts  the  graphics  cursor  on. 

CurRgt  Idofes     gm{diios  eursta-  right  one  space. 

Bell  Sounds  the  terminal  bell. 

CurLft  IVfoves  the  graphics  cursor  left  one  space. 

CurUp  Moves  the  graphics  cursor  up  one  line. 

CurDwn  Moves  the  graphics  cxu^or  down  one  line. 
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Font  Handling  Commands: 


Command 


Font  Specifies  the  buffer  from  which  BASIC09 

selects  its  isnt  characters. 

TCharSw  Selects  or  desdects  transpar^t  characters. 

BoldSw  Selects  or  deselects  bold  charactei^. 

PropSw  Selects  or  deselects  proportional  characters. 

ErEoWndw  Erases  from  the  graphics  cursor  to  the  end 

of  the  window. 

Clear  Erases  window  and  homes  the  cursor. 

CrRtn  Performs  a  carriage  return  by  moving  the 

cursor  doAvn  one  line  and  to  the  actreme  left 
of  the  window. 

ReVOn  Turns  reverse  video  on. 

ReVOff  Turns  reverse  video  off. 

UndlnOn  Turns  the  underline  function  on. 

UndlnOff  Turns  the  underline  function  off. 

BlnkOn  Turns  blinking  characters  on  (only  for  hard- 

ware text  screens). 

BInkOff  Turns  blinking  characters  off  (only  for  hard- 

ware text  screens). 

InsLin  Inserts  a  blank  line  at  the  graphics  cursor 

position. 

DelLin  Deletes  the  line  at  the  graphics  cursor 

position. 
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ARC  Draw  an  arc 


Syntax:     RUN  GWlL2([path,rARC"[,mx,my], 
xrad,yrad,xcorl,ycorl,xcor2,  ycor2) 


Function:  Draws  an  arc  at  the  current  or  specified  draw  posi- 
tion with  the  specified  X  and  Y  radius.  If  you  specify  the 
same  radius  for  both  X  and  Y,  the  function  draws  a  circular 
arc,  otherwise  the  arc  is  elliptical.  The  X  coordinates  are  in 
the  range  0-639.  The  Y  coordinates  are  in  the  range  0-191. 

ARC  begins  drawing  from  the  point  on  the  screen  closest  to 
the  first  set  of  coordinates  (xcorl,  ycorl).  It  stops  at  the  por- 
tion of  the  screen  closest  to  the  second  set  of  coordinates 
(xcor2,  ycor2).  Yon  can  determine  on  which  side  of  the  line 
ARG  draws  by  selecting  which  set  of  coordinates  is  the  begin- 
ning and  which  set  is  tlie  end. 


Parameters: 

path 

mx,my 


xrad 
yrad 

xcorl, ycorl 
xcor2,ycor2 


The  route  to  the  window  in  which  you  want  to 
draw  an  arc. 

The  X-  and  Y-coordinates  for  the  center  of  the 
arc.  If  you  do  not  specify  mx  and  my,  BASIC09 
uses  the  current  draw  pointer  position. 

The  radius  of  the  arc's  width. 

The  radius  of  the  arc's  height. 

The  beginning  and  ending  coordinates  to  an 

imaginary  line  from  which  the  function  draws 
an  arc.  The  line  is  relative  to  the  center  of  the 
arc  (the  center  point  is  at  0,0  for  these  coordi- 
nates) and  extends  through  the  two  coordi- 
nates from  one  edge  of  the  screen  to  the  other. 


Examples: 


RUN  GFX2C"ARC",  50 ,100, 50, 100, 50, 150) 
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Sample  Program: 

This  procedure  draws  a  series  of  diagonally-cut  arcs  on  a  graph- 
ics window  screen. 

PR  D  C  EDURE  ar  c  i  ng 

□DIM  MX , MY, X RAD, YR AD, XC0R,YC0R,XCDR2,YGaR2: INTEGER 

□DIM  T,X,Y,Z: INTEGER 

3PRINT  CHR$(12) 

□FOR  T=1   TO  90  STEP  2 

□RUN  GFX2C"ARC",318,9t,tSB,T,fl,1  ,0,1) 
□RUN  GFX2("ARC",324,95,1Sa,T,1  ,0,1  ,1  ) 

□NEXT  T 
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BAR 


Fill  a  rectangle 


%iitax:     RUN  GFX2([patb,Y'BAB."[,xcorl,ycorl],xcor2, 
ycor2) 


Function:  Fills  a  rectangular  area  defined  by  two  sets  of  coor- 
dinates. BAR  defines  its  area  with  an  imaginary  diagonal 
line  from  the  first  set  of  coordinates  to  the  second  set  of  coor- 
dioaies.  1%e  %.  eooriinal^s  are  iii  the  timge  0-639.  The  Y 
coordinates  are  in  the  reinge  0-191. 


Parameters: 

path 

xeorl^orl 


xcor2,ycor2 


The  route  to  the  window  in  wWdb.  fm.  wnt  to 
^awabar. 

The  beginning  coordinates  of  the  line  defining 
the  area  to  fill.  If  you  omit  these  coordinates, 
BAR  uses  the  draw  pointer  position.  the 
previous  section  "The  Graphics  Cursor  and 
The  Draw  BMnter."  Also  see  SETDPTR. 

The  ending  coordinate  of  the  line  dinning  the 
area  to  fill. 


RUN  GF X2 C "BAR" ,200,1  00) 


RUN  GFX2("BAR",0,0,100,50) 


Sample 

This  inoceiure  draws  a  bar  chart  on  a  window  screen. 

PROCEDURE  DSgraf 

ODIM  CDLDR,T,X ,XCDR1  .YCQRl  ,  XCDR2 , YCDR2 : 

INTEGER;   RESP DNSE : STR I NG [ 1 ] 

□PRINT  CHR$(12) 

□RUN  GFX2("DEFC0L") 

□C0LDR=13  \   XCDR1-10  \  YCDR1=180 

DXCDR2=XCQR1 +40 

□RUN  GFX2("CURQFF") 
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□FOR  T=1    TG  10 
DREAD  YCDR2 

DRUM  GFX2("CDLDR", COLOR) 

DRUM  GFX2("BAR",XC0R1  ,YC0R1  , XC0R2 , YC0R2) 
□RUN  GFX2C"C0LDR",7) 

DRUN  GFX2("B0X" , XCDR1  ,YCDR1  , X CO R2 , YC □R2 ) 

□CDL0R  =  CDLDR  +  1    \   X  COR  1 = X  COR  1 + 5 0    \   X C □R2  =  X C0R1 + 4 0 

□NEXT  T 

□PRINT  \  PRINT  "         05-9  Sales  Chart" 

□RUN  GFX2("B0X" , 0 , 0 ,51 0 , 1 80) 

□GET  #1  ,  RESPONSE 

□RUN  GFX2("CURDN") 

DP)?  I  NT  CHR*C12) 

□END 

□DATA  170,150,140,130,110,90,70,60,50,30 
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BELL  Ring  the  terminal  bell 


K    BUN  ©OTf *1EIJ/1 

Function:  Rings  the  tenninal's  bdl  (produces  a  beep  through 
the  speaker). 

Parameters:  None 

Examples: 

RUN  GFX2C"BELL") 
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BLNKON  Character  blink  on 
BLNKOFF  Character  blink  off 

Syntax:    RUM  QFmi[pBm,rMMmm'l 
RUN  GFX2([patb,Y'BLmOWF") 


Functiou;  Executing  H^NIOON  cau^s  all  subsequent  charac- 
tears  sent  to  a  window  on  a  hardware  screen  to  blink.  A  hard- 
ware screen  is  one  of  the  predefined  device  windows  /Wl 
through  /W7.  Executing  BLNKOFF  cancels  a  previous  blink 
command;  characters  already  blinkii^  continue  to  do  so.  Blink 
does  not  operate  on  graphics  windows. 

I^ameters: 

path  The  route  to  the  window  in  which  you  want  to 

blink  characters. 

Examples: 

RUN  0FX2C-BLNKDN") 

RUN  GFX2("BLNKDFF") 
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BOLDSW  Switch  bold  characters  on  or  off 


%Btax:  mmmmipao^mciiLmw'/'smcm 

Function:  Causes  characters  to  display  in  either  regular  or 
bold  typeface.  The  default  is  regular  tj^jeface.  BOLD  only 
works  on  grapfaics  scre&as. 

Parameters: 

path  The  route  to  the  window  in  which  you  want 

bold  characters. 

switch  Can  be  either  "ON"  or  "OFF."  If  switch  is 

"ON,"  subsequent  characters  are  bold.  If 
switch  is  "OFF,"  subsequent  characters  are 
not  bold. 

Examples: 

RUN  GFX2("BDLDSW","0N") 

Sample  Program: 

This  procedure  demonstrates  the  BOLDSW  function  by  display- 
ing both  bold  and  normal  text  on  a  window  screen. 

PROCEDURE  bold 

DDIM  LINE:STRING 

□DIM  LETTER:STRING[1  ] 

□DIM  T, J, K,FLA6: INTEGER 

□RUN  GFX2("CLEAR") 

□FLAG=1 

□FDR  T=1    TO  8 

□READ  LINE 

□FDR  J*1  TO  LENCLINE) 

□  LETTER  =  MID$CLINE, J,1  ) 

□  IF  LETTERO"!"  AND  LETTER<>"#"  THEN 
□PRINT  LETTER; 

□ENDIF 

OIF  LETTER'"!"  THEN 
□FLAG-FLAG»-1 
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DIF  FLAG>0  THEN 

□RUM  GF X 2  C "BQLDSW" , " DF F " ) 

□  ELSE 

□RUN  GFX2("BDLDSW","DN") 

□ENDIF 

DENDIF 

DIF  LETTER="#"  THEN 

□PRINT  GHR$t343; 

□ENDIF 

□NEXT  J 

□PRINT 

□NEXT  T 

□PRINT  \  PRINT 
□END 

□DATA  "This  is  a  demonstration  of" 
□DATA  "the   !Bold!   function  of" 
□DATA  "BASICOB's  GFX2  module." 

□DATA   "Use   the  command" 

□DATA   "!RUN  GF X 2 ( #BDLDSN# , #QN# ) ! " 

DDATA  "to  t-um  boldfaee  on." 

□DATA   "Use    !RUN  GF X 2 ( #BDLDSW# , #DFF# ) ! " 

□DATA  "to  turn  boldface  off" 
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BORDER  Set  the  border  color 


Syntax:    RUN  GFX2([paai,]"BORDER",co/ar) 

Function:  Resets  the  palette  register  that  affects  a  window's 
border  color  (Register  0)  to  the  specified  color  code.  For  infor- 
mation on  the  palette  and  on  screen  colors,  see  'The  Palette" 
and  Table  9.7  earlier  in  this  chapter. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

change  border  color. 

color  One  of  the  current  palette  colors.  Color  can  be 

eiiber  a  eoeigtaiit  or  a  variable. 

Examples: 

RUN  GFX2("B0RDER",1 ) 

Sample  Program: 

This  procedure  lets  you  select  different  border  colors  by 
pressing  [T]  or  Q  to  select  higher  or  lower  color  codes. 
Press  [g]  to  end  the  procedure, 

PROCEDURE  border 

GDIM  COLOR : INTEGER 
□DIM  KEY:STRING[1 I 
□COLOR'S 

QRUN  GFX2C"CLEAR"> 

□WHILE  KEY<>"q"  AND  KEY<>"Q"  DO 

□GET  #1 ,KEY 

□IF  KEY="-"  OR  KEY="="  THEN 

□COLOR-CDLOR-1 

DEMDIF 

□  IF  KEY="+"  OR  KEY-" 5"  THEtf 

□CDLDR=CDLDR+1 

□ENDIF 
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DIF  C0LQR>15  OR  COLOR<0  THEN  CDL0R=8 
QEMPIF 

DRUN  GFX2C"B0RDER", COLOR} 
DRUM  GFX2C"CURXY",0,0) 
□ENDWHILE 
□END 
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BOX  Draw  a  rectangle 


Syntax:    BUN  GFX2i[patb,]"BaK"[,xeorI,ycorI], 
xeor2,ycor2) 


Function:  Draws  a  rectangle.  BOX  defines  its  area  with  an 
imaginary  diagonal  line  from  the  first  set  of  coordinates  to 
the  second  set  of  coordinates.  BOX  does  not  reset  the  draw 
pointer.  The  X  omrdinates  are  in  tibe  r^mge  0^639.  The  Y 
coordinates  are  in  the  range  0-191. 

Parameleri: 

path  The  rent©  to  the  window  in  which  fm  want  to 

draw  a  box. 

xcorljcorl  The  beginning  coordinates  for  the  line  that 
defines  the  rectangle  to  drawn.  If  you  omit 
these  coordinates,  BOX  uses  the  draw  pointer 
position. 

xcor2,cor2  The  ending  coordinates  for  the  line  that 
defines  the  rectangular  area  to  be  drawn. 


RUM  GF)!2C"BDX",2BB,1fl0) 
RUN  GFX2<"BDX",0,0,1fl0,50) 

Sample  Program: 

This  procedure  draws  a  series  of  progressively  smaller  boxes  of 

different  colors  on  a  window  screen.  Then,  it  rapidly  changes  the 
colors  of  the  boxes  to  produce  a  hypnotic  effect. 

PROCEDURE  hypbox 

□DIM  X,¥,Xi ,Y1 ,T,R,CDLDR! INTEGER 

ODIM  KEY:STRING[1 ] 

OKEY="" 

DX=18  \Y=6 

0Y1=185  \X1=621 

□RUN  GFX2<"CLEAR") 
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□FOR  T=0  TO  15 
□COLaR=T 

□RUN  GFXSC'CDLOR" , 3) 

□RUN  GFX2C"B0X",X,Y,X1 ,Y1 ) 

□RUN  GFXaC'CQLOR", COLOR) 

□RUN  0FX2C"FILL",X-1 ,Y-1) 

□X=X+18  \Y=Y+6 

□  XI  =X1 -1 8  \Y1 =Y1 -6 

□NEXT  T 

□WHfLt  iCE¥=M»i  00 
□RUN  INKEY(KEY) 
□FDR  T=1    TO  1G 
□R=RNDC65) 

□RUN  GFX2("PALETTE",T,R) 
□NEXT  T 

□ENDWHILE 

□RUN  GFX2C"DEFCDL") 
□END 
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CIRCLE  Draw  a  circle 


Syntax:    RUN  GWm(l^m,rcmCin^eo€n-,ycorl 
radius) 


Functioii:  Draws  a  circle  with  a  specified  radius.  If  you  specify 
coordinates,  CIRCLE  uses  them  for  the  center  point.  Other- 
wise, CIRCLE  locates  the  center  of  the  circle  at  the  current 
draw  pointer  position.  See  "The  Graphics  Cursor  and  the 
Draw  Pointrar"  earlier  in  this  section.  Also  see  SETDPTR. 


Parameters: 

path 

xcor^cor 


The  route  to  the  window  in  which  you  want  to 
draw  a  circle. 

The  coordinates  for  the  circle's  center.  The  X 
coordinates  are  in  the  range  0-639.  The  Y 
coordinates  are  in  the  range  0-191. 


radius  The  radius  of  the  circle. 

Examples: 

RUN  GFX2C"C I RCLE" ,180) 

RUN  GFX2C"CIRCLE",100,200,B0) 
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Samp]®  Program: 

This  procedure  uses  circles  to  produce  a  geometric  design. 

PROCEDURE  ciraroand 

□DIM  T,X,Y: INTEGER 

□PRINT  CHR$C12) 

□RUN  GFX2("C0L0R",1  ,2) 

□FOR  T=1   TO  130 

□X=1 50»S I N(T)+320 

□Y=25*CDSCT)+96 

□RUN  GFX2C"CIRCLE",X,Y,100} 

□NEXT  T 

DRUN  GFX2C"C0L0R",3,2) 

□FDR  T=1    TO  45 

□X=150*SINCT)+320 

t]Y*tS*G:0SCT3!*96 

□RUN  GFX2<"CIRCLE",X,Y,1  003 

□NEXT  T 

□END 
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CLEAR  Clear  the  screm 

Syntax:     RUN  GFX2([path,]"CLEAR") 

Function:  Gleai'S  the  current  working  area  of  a  window. 
CLEAR  does  not  change  the  location  of  the  draw  pointer  but 
does  set  the  text  cursor  and  graphics  cursor  location  to  the 
upper  left  corner  of  the  window. 

Parameters: 

path  The  route  to  the  window  you  want  to  clear. 

Examples: 

RUN  GFX2C"CLEAR") 
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COLOR  Set  screen  colors 


Syntax:     RUN  GFX2([patJi,]"COLOR", 

foregroundl,  background^,  border]) 


Function:  Changs  any  of  the  foreground,  background,  or  the 
border  colors.  COLOR  does  not  change  the  draw  pointer 
position. 


Parameters: 

path 

foreground 

background 

border 

Examples: 


The  route  to  the  window  in  which  you  want  to 
change  one  or  more  screen  or  text  colors. 

The  register  number  for  the  foreground 
palette. 

The  register  number  for  the  background 
palette. 

The  register  number  for  the  border  palette. 
Changing  the  border  color  for  any  window  on  a 
screen,  changes  the  border  color  for  all  win- 
dows on  the  same  screen. 


RUN  GFX2("C0LDR"  ,  1  ) 
RUN  GFX2("CDLDR",1 ,2) 
RUN  GFX2{"CDLDR'M  ,2,1 ) 
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Sample  Program: 

This  procedure  fills  a  window  screen  with  multicolored  filled 
circles. 

nUIM  X ,Y,W,Z,T: INTEGER 
02=1 

ORUN  GFX2("CDLDR" ,1,0,03 

ORUN  GFX2C"CLEAR") 

QFDR  T=1   TO  80 

0X=RND(e35)+4 

0Y=RNDC185)+5 

□W=RND(50+S) 

DZ=Z+1 

□IF  Z>3  THEN  Z=1 

□ENDIF 

□RUN  GFX2("CIRCLE",X,Y,W) 
□RUN  GFX2C"C0LDR" ,Z) 
□RUN  GFX2C'FILL",X,Y) 
□NEXT  T 

□RUN  GFX2C"GDLDR",3,2,2  3 

□END 
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CRRTN  Carriage  return 

Syntax:     RUN  GFX2([paai,]"CRRTN") 

Function:  Causes  BASIC09  to  send  a  caniage  return  to  a 
window.  The  cursor  moves  down  one  line  and  to  the  extreme 
left  of  the  window. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  a 

carriage  return. 

Examples: 

RUN  GFX2("CRRTN") 
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CURDWN  Cursor  down 

Syntax:    HUN  GFX2([paai,]«CURDWN") 

Function:  Moves  the  cuisor  dcmm  one  text  line.  The  X-coordi- 
nate,  or  cdhxmn  posilioE,  ranaii^  tibs  same. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

move  the  cursor. 

Examples: 

RUN  GFX2<"CURDWN") 
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CURHOME 

Syntax:     RUN  GFX2([pat/i,]"CURHOME") 

Flinctioii:  Moves  the  text  cursor  to  the  top  left  eom^  of  the 
screen. 

Parameters: 

puih  The  route  to  the  window  where  you  want  to 

reset  the  cursor 

Examples: 

RUN  &FS<2C"'CUiH0ME") 
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CURLFT  Move  ewmm  left 

Syntax:     RUN  GFX2([pai/i,]"CURLFT») 

Function:  !Mbves  the  cursor  one  character  to  the  left. 
Parameters: 

path  The  route  to  the  window  where  you  want  to 

move  the  cursor. 

Examples: 

RUN  GFX2("CURLFT") 
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CUROFF  Turn  off  cursor 

SyntasK    MUf  GIX2([pa£faJ"CTOafr') 

Funclion:  Makes  the  cursor  invisible. 
Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

turn  the  cursor  off. 

Examples: 

RUN  GFX2("CUR0FF") 
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CURON  Turn  on  cursor 

Slyntax:    EUN  GFX2(tpaa»FCUBP!r) 

Function:  Makes  the  text  curscn- visible. 
Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

turn  the  cursor  on. 

Examples: 

RUN  GFX2<"CUR0N") 
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CURRGT  Move  cursor  right 

Syntax:    RUN  aFX2CtpaaijCUKBGT") 

Functaon:  Movies  the  cursor  one  character  to  the  right. 
Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

move  the  cursor. 

RUN  GFX2C"CURRGT") 
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CURUP  Move  cursor  up 

Syntax:    RUN  GFX2(liiath,]«CURUP") 

Function:  Moves  the  cursor  up  one  line. 
iParaniieters: 

path  The  route  to  the  window  in  which  you  vrant  to 

move  the  cursor. 

Examples: 

RUN  wim^mm?"^ 
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CURXY  Set  cursor  position 

^tax:     RUN  GFX2([pa£h,]"CURXY",coiHinii^ow) 

Function:  Moves  the  cursor  to  the  specified  column  and  row 
position.  The  column  and  row  coordinates  are  relative  to  the 
window's  currait  character  width  and  depth. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

move  the  cursor. 

column  The  column  (horizontal)  position  for  the 

cursor. 

row  The  row  (vertical)  position  for  the  cursor. 

Examples: 

RUN  GFX2<"CURXY'M0,10) 
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CWAREA  Change  ivorking  area 


%ntax:     RUN  GFX2([iia*fcJ"CWAREA^xcor^or,fiHre3r, 
sizey) 


Function:  Restricts  output  in  the  window  to  the  specified  area. 
The  ussir  must  be  the  same  or  smaller  than  the  previous 
■working  area.  When  a  window's  working  area  is  changed, 
OB-9  scales  graphic  and  text  coordinates  £md  gra|ihic  images 
to  the  new  proportions.  Tsxt  characters  remain  tiie  same  size. 


Parameters: 

path 


xcor^or 


siz&c 


The  route  to  the  window  in  which  you  want  to 
^im^  the  working  area. 

The  beginning  coordinates  (the  upper  left  cor- 
ner) for  the  new  working  area,  relative  to  the 
original  '(^ndow.  The  coordinates  art  ^m&i,  on 
the  character  column  and  row  size  of  the  origi- 
nal window. 

Designates  the  number  of  columns  in  the  new 
working  area. 

The  number  of  lines  available  in  the  new 
working  area. 


Examples: 

RUN  GFX2C "CWAREA" , 1 0 , 0 ,40 , 1 0) 
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Sample  Program: 

This  procedure  makes  the  working  area  in  a  window  progres- 
sively smaller,  filling  each  area  with  a  different  color.  It  then 
changes  the  areas'  colors  rapidly  to  produce  a  hypnotic  effect. 

PROCEDURE  hypnobox 

□DIM  X,Y,X1 ,Y1 ,T,R, COLOR: INTEGER 

□DIM  KEY:STRINGC1 ] 

aKE'V-'*" 

QX=3  \Y=1 

□X1=80-CX+X)  \Y1=24-CY+Y) 

□FDR  T=0  TO  10 

□RUN  GFX2("C0LQR",3,T) 

□RUN  GFX2("CLEAR") 

□RUN  GFX2C"CNAREA",X,Y,X1 ,Y1 ) 

□X=X+3  \Y=Y+1 

□  XI  =80-(X  +  j()  \Y1-24-(Y  +  Y) 

□NEXT  T 

DiUN  GFX 2C "COLOR" , 3 , § > 
□WHILE   KEY=""  DO 
□RUN  INKEYCKEY) 
□FOR  T-1   TO  16 
QR-RND(65) 

□RUN  GFX2t"PALETTE",T,R) 

□NEXT  T 
□ENDWHILE 

OR¥N  Gf  liCBEFtOL") 

□RUN  GFX2C "GW ARE  A" ,0,0, 80 , 24 ) 

□END 
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DEFBUFF  Define  GET/PUT  buffer 


Syntax:    RUN  GFX2("DEFBUFF',p?iiHiJ,feiiffer,size) 

Function:  Defines  a  buffer  for  GET/PUT  operations. 

When  you  define  a  buffer,  you  do  so  by  group  number  and 
buffer  number.  Each  group  you  define  allocates  eight  kilobytes 
of  memory.  The  system  needs  30  bjrtes  of  the  fel^ck  for  over- 
head, leaving  8162  bytes  free.  Within  the  group,  you  can  allo- 
cate one  or  more  buffers.  Select  a  group  number  and  a  buffer 
number  as  indicated  in  the  following  "Parameters"  section. 
Use  these  numbers  in  future  references  to  the  buffer. 

A  GET/PUT  buffer  remains  allocated  until  you  use  the  KILL- 
BUFP  fcnetion  %o  remove  it  feom  yow  ^dbffi*s  mmmf  .  !fe 
more  information  on  Get/Put  buffers,  s^  KILLBUFP,  PUT, 
GET,  and  GPLOAD. 

Parameters: 

hufler 
size 


Notes: 

One  method  of  selecting  a  group  number  is  to  use  SYSCALL 
and  the  Get  ID  (103F  00)  systCTo,  call  to  obtain  your  user's 
process  ED  number.  Tlien,  nse  this  ID  numb©:  as  a  group 
number.  Using  this  system  for  all  GET/PUT  buffer  operations, 
ensures  against  group  number  overlapping.  See  the  SYS- 
CALL command  for  more  information. 

Examples: 

RUN  GFX2C"DEFBUFF",1 ,5,4000H0) 
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assign  to  the  buffer  you  create. 

The  size  of  the  buffer,  in  the  range  of  1  to 
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DEFCOL  Set  defiault  colors 

Syntax;  WDN  Qwmtpa^rmmmn 

Function:  Sets  the  palette  registers  back  to  their  default  val- 
ues. The  type  of  monitor  jou  have  determines  the  actual  hues. 
See  **The  Palette"  and  Tkhte  t.T  earlier    this  section. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

restwe  the  original  palette  registers. 

Examples: 

RUN  GFX2C"DEFCDL") 
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DELLIN  Delete  current  line  of  text 


Syntax:     RUN  GFX2([iiaa,]'*DELLIN") 

Function:  Deletes  the  line  on  which  the  cursor  is  resting  and 
closes  the  space.  DELLIN  operates  on  both  text  and  graphics 
screens. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

delete  a  line. 

Examples: 

RUN  GFX2("DELLIN") 

Sample  Program: 

This  procedure  draws  a  series  of  various  colored  concentric  cir- 
cles, then  produces  a  lemon  shape  by  removing  slices  of  the  circle 
with  DELLIN. 

PROCEDURE  slice 

QDIM  X,Y,R,T, COLOR: INTEGER 

DRUN  GFX2C "CLEAR") 

□CDLDR=0 

OX=320 

0Y=96 

OFQR  T'-ISS  TD  10  STEP  -10 
QRUN  GFX2t"C I RCLE" , X , Y , T) 
□NEXT  T 

□FOR  T=140  TO  320   STEP  10 
□RUN  GFX2C"CDLDR", COLOR) 
□RUN  GFX2("FILL",T,96) 
□C0LDR=C0L0R+1 

□NEXT  T 

□RUN  GFX2("CURXY",0 ,8) 
□FOR  T=1   TD  8 
□RUN  GFX2C"DELLIN") 
□NEXT  T 

□RUN  GFX2<"CDLaR",3,2) 

□END 
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DRAW  Draw  a  polyline  figure 


^tax:     RUN  GFX2([paai,]"DRAW",op«Qn  Usti 

Function:  Draws  in  the  directions  specified,  and  for  the  dis- 
tances specified,  in  an  option  list.  The  option  list  is  a  string  of 
ebameters  and  numbers.  You  can  separate  options  with  spaces 
or  commas.  Yoa.  must  include  commas  between  the  two  coordi- 
nates for  the  B  and  U  options. 


Parameters: 

path 

optim  Ust 


Options: 

Nnum 

Snum 

Enum 

Wnum 

NEnum 

SE  num 

SWnum 

Aval 


JJxcor^MMr 


The  route  to  the  window  in  which  you  want  to 
draw. 

A  string  consisting  of  one  or  more  of  ti»  M- 
lowing  options: 


draws  north  (up)  num  units. 

draws  south  (down)  num  units. 

draws  east  (right)  num  units. 

draws  west  (left)  num  units. 

draws  northeast  (up  and  right)  num  units. 

draws  northwest  (up  and  left)  num  units. 

draws  southeast  (down  and  right)  num  units. 

draws  southwest  (down  and  left)  num  units. 

rotates  the  draw  axis.  PossiHe  mlaes  are: 

0  =  normal 

1  =  90  degrees 

2  =  180  degrees 

3  =  270  degrees 

draws  a  relative  vector  to  the  specified  coordi- 
nates. Xcor  and  ycor  are  relative  to  the  cur- 
rent draw  pointer  position.  The  draw  pointer 
location  does  not  change.  Xcor  and  ycor  must 
be  separated  hy  a  comma. 
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Bxeorjcor       prodwees  a  bla»k  line  (laoyes  the  cursor  but 
does  not  draw).  The  xcor  and  ycor  cocnrdinateEi 

are  relative  to  the  current  draw  pointer  loca- 
tion. If  you  specify  relative  coordinates  located 
offscreen,  you  cannot  see  subsequent  lines. 

Examples: 

RUN  GFX2C"DRAN","N1 0,E10,S10,W10") 

Sample  Program: 

PROCEDURE  drawing 

DDIM  T,  X ,Y, COLOR: INTEGER 

OCQLDR=0 

DRUN  GFX2<"CLEAR") 

□FOR  T=1   TO  96  STEP  6 

OR  UN  6F  5(  2  C  "  SE  TDPTR  " ,  320  , 96  ) 

□FDR  Y=0  TO  3 

□C0LaR=MaDCY,2) 

DRUN  ©FX2€ "GDLQR" .COLOR ) 

□FOR  X=1  TO  4 

□READ  DR$ 

□DR$="A"+STR$< Y)+DR$+STR*CT) 
□RUN  GFX2C"DRAW" ,DR$) 
QNfKT  H 

□NEXT  Y 
□RESTORE 
□NEXT  T 

□RUN  GFX2C"C0L0R",3) 
□END 

□DATA  "N","E","S","W" 
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DWEND  Defvice  window  end 


Syntax:     RUN  GFX2([pa/:h,]"DWEND") 

Function:  Deallocates  the  device  winlow  you  initialized  with 
DWSET  and  INIZ.  If  the  window  deallocated  is  the  last  device 
window  on  the  screen,  BASIC09  returns  the  screen  memory  to 
tbi  system.  DWEND  automaticsdly  positions  you  in  the  nesct 
device  window,  a  result  siindlar  to  pressing  I  clear  I.  %u.  cam 
use  this  function  with  DWSET  to  redefine  a  device  window  to 
a  different  type. 

Parameters: 

path  The  path  number  of  the  window  you  wish  to 

end.  Path  can  be  a  constant  or  variable. 

Examples: 

RUN  GFX2("DWEND") 

RUN  GFX2CPATH, "DWEND") 

RUN  GFX2(3, "DWEND") 

Sample  Program: 

From  /TERM,  this  procedure  temporarily  opens  a  path  to 
Window  3,  displays  the  new  window,  draws  a  design,  then 
retttrns  to  the  /TERM  screen  and  closes  the  path. 

PROCEDURE  decorate 
□DIM  PATH.T, Y: INTEGER 
HDPEN  #PATH,"/W3":WRITE 

□RUN  GFX2CPATH, "DWSET", 7,0 ,0,80 ,24,3,2,2) 
□RUN  GFXaCPATH, "SELECT") 

□  Y=1 

□RUN  GFX2(PATH,"CDL0R",3,2) 
□FDR  T=1   TD  18S  STEP  3 
□Y=Y+1 

mUH  GrX2( PATH  ,  "ELL  I PSE"  ,  320  , 96 , T ,  Y ) 

□NEXT  T 

DRUN  GFX2(PATH,"CQLDR",1  ,2) 
DFOR  T-185  TO  1    STEP  -6 
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□RUN  GFX2(PATH,"ELLIPSE",320 ,96,T, Y) 
QIF  INTCT/3)=T/3  THEN 
OY-Y+1 
□END IF 

□NEXT  T 

□RUN  GFX2(1 ."SELECT") 
Df UN  GF X  2 ( P ATH , "DWE ND" ) 
□CLOSE  #PATH 
□END 
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DWPROTSW  Device  window  protect  switch 


^tax:     RUN  GFX2([paiA,]"DWPROTSW","switeli") 

Function:  Lets  you  unprotect  one  device  window  and  set  other 

device  windows  on  top  of  it. 

OS-9  on  the  Color  Computer  3  normally  uses  a  protected  win- 
dowing system  that  does  not  allow  window  devices  to  overlap. 
Removing  the  window  protection  with  DWPROTSW  lets  one 
device  window  exist  on  the  same  screen  area  as  another  win- 
dow ^i^ce.  Because  this  might  destroy  the  contents  of  an 
unprotected  window,  you  need  to  use  care  with  this  function. 

Parameters: 

path  The  route  to  the  window  you  want  to 

unprotect. 

switch  Either  OFF  to  tera  off  protection,  or  ON  to 

turn  on  protection.  The  default  is  ON. 

Examples: 

RUN  GFX2C"DWPRDTSW",aFF) 
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DWSET  Deviee  window  set 


Syntax:     RUN  GFX2([path,]"TmSET",format,xcor,ycor, 
width,lengtb,fyreground,  background,  border) 


Function:  Defines  a  device  window.  Normally,  you  first  open  a 
path  to  a  window,  then  use  DWSET  to  set  the  window  format, 
location,  size,  and  colors, 


Parameters: 

ptiith 
prmai 

xcor,ycor 

width 

length 

foreground 

background 

border 

Examples: 


The  route  to  the  window  you  are 

The  code  for  the  type  of  screen  you  mnt  to 
establish.  See  Table  9.6  at  the  beginning  of 
this  section  for  the  formats  available. 

The  coordinates  (character  column  and  row)  of 
the  lappa*  left  comer  of  the  screen  you  want  to 
create. 

The  width  (in  characters)  of  the  new  window, 
The  depth  (in  lines)  of  the  new  window. 
The  code  for  the  window's  foreground  color. 
The  code  for  the  window's  background  color. 
The  code  for  the  window's  border  color. 


RUN  &f% 2 C "DWSET" , 06 , 50 , 1  0 0 , 5 0 , 1  0 , 20 , 1 2 , 9 > 

Sample  Program: 

This  procedure  opens  a  path  to  Window  3,  uses  DWSET  to  define 
the  new  window,  displays  the  new  window,  and  draws  a  graphic 
lemon  shape.  It  then  uses  SELECT  to  return  to  the  /TERM  win- 
fltwr  m  screen,  deallocates  WMow  3,  and  closig  the  path. 
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PRDCEBUBE:  lemon 

DDIM  PATH, T,X,Y: INTEGER 

□  □PEN   #PPiTH  ,  "/W3"  :  NR  ITE 

□RUN  GFX2CPATH,"DWSET", 7,0 ,0,80 ,24,3,2,2) 
□RUN  GFX2(PATH, "SELECT") 

□Y  =  1 

□RUN  GFX2CPATH, "COLOR", 0,2) 
□FOR  T=1   TO  185  STEP  3 
QY=Y+1 

□RUN  GFXatPATH, "ELLIPSE", 320, 96,T,Y) 

□NEXT  T 

□  X  =  T 

□RUN  GFX2(PATH , "COLOR" ,3,2) 

QFQR  T=62  TO  1   STEP  -3 

DRUN  ©FX 2< PATH , "ELL  I PSE" , 320 , 9S , X , T) 

□IF   INTCT/3)=T/3  THEN 

□X=X+1 

□ENDIF 

□NEXT  T 

□RUN  GFX2C1 , "SELECT") 
□RUN  GFX2CPATH,"DWEND") 
□CLOSE  -CPATH 
□END 
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ELLIPSE  Draw  an  ellipse 


xrad,yrad) 

Function:  Draws  an  eHipse  with  the  center  at  the  current 
draw  pointer  position  or  at  lite  Reified  X,Y  GO(»fiinatei.  The 
X  coordinates  are  in  the  range  5-639.  The  Y  coordinates  are 
in  the  range  0-191. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

draw. 

xcorjcor  The  coordinates  for  the  ellipse's  center.  If  you 

omit  these  coordinates,  ELLIPSE  uses  the 
current  draw  pointer  position. 

xrad^rad        The  radii  of  the  ellipse's  length  and  height. 
Examples: 

RUN  GFX2("ELLIPSE",100,B0) 

RUN  GFX2C"ELLIPSE'M00,12S,100,1  01 

Sample  Program: 

This  program  uses  ELLIPSE  to  draw  a  graphic  design  shaped 
like  a  Christmas  tree  decoration. 

PROCEDURE  xbulb 
□DIM  T,Y: INTEGER 
□Y  =  1 

□RUN  GFX2C"CDLQR",3,2) 
□RUN  GFX2C"CLEAR") 
□FDR  T=1   TO  180  STEP  3 
□Y=Y+1 

□RUN  OF  X  2  ( ■•  E  L  L I P  S  E " ,  320  , 96 ,  T ,  Y  ) 

□NEXT  T 

□RUN  GFX2("C0LDR" ,1,2) 
□FOR  T=180  TD  1   STEP  -6 
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□RUN  GFX2("ELL IPSE", 320 ,9G,T, Y) 
□IF  INT(T/3)=T/3  THEN 

□Y=Y+1 
□ENDIF 
□NEXT  T 

□RUN  GFX2("C0LDR",3,2} 
□END 
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EREOLINE  Erase  to  end  of  line 


Syntax:     RUN  GFX2([iia*h,]«EREOLINE") 

Function:  Deletes  the  portion  of  the  current  line  from  the  cur- 
sor to  the  right  side  of  the  window. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

erase  a  portion  of  a  line. 

Examples: 

RUN  GFX2C"EREDLINE") 

Sample  Program: 

This  procedure  u^s  ESEOI^E  to  produce  a  series  c€  steps 
down  the  screen. 

PROCEDURE  steps 
ODIM  T,J,K: INTEGER 
ORUN  GFX2("CDLDR",2,3) 
QRUN  GFX2C"CLEAR") 
DRUN  GFX2C"CDLDR",3,2) 
□FDR  T=0  TD  22 
QJ=T»3 

DRUM  GFX2("CURXY", J,T) 
□RUN  GFX2<"EREDLINE") 

DNEXT  T 
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EREOWNDW  Erase  to  end  of  window 


Syntax:     RUN  GF3E2(Ipaai,]"EREOWNBW") 

Function:  Deletes  all  the  lines  in  a  window  from  the  line  on 
which  the  cursor  is  positioned  to  the  bottom  of  the  window. 

Paramet^s: 

path  The  route  to  the  window  in  which  you  want  to 

delete  screen  contents. 

Examples: 

RUN  GFX2<"EREDWNDW") 
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ERLINE  Delete  current  line  of  text 


Syntax:     RUN  GFX2{[iiaaiJ"ERLINE") 


Function:  Deletes  the  current  line  (on  which  the  cursor  is  rest- 
ing) from  the  window  but  does  not  close  the  space. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

remove  the  contents  of  a  screen  line. 

Examples: 

RUN  GFX2C"ERLINE") 

Scunple  Program: 

This  procditirB  draws  a  biitl*s-i^  desipi,  then  slices  it 
with  the  ERLINE  fiinction. 

PROCEDURE  cut 

DDIM  X,Y,R,T, COLOR: INTEGER 

□CDLDR-0 

QX-320 

DY-96 

□RUN  GFX2t"CLEAR") 

□COLOR=a 

□FOR  T=185  TO  10  STEP  -10 
DRUN  GFX2("CIRCLE",X,Y,T) 
ONEXT  T 

OFDR  T=r40  TO  320   STEP   1 0 
□RUN  GFX2("CDL0R", COLOR) 
□RUN  GFX2C"FILL",T,96) 
0C0L0R=CQLDR+1 
□NEXT  T 

□FOR  T=2  TO  22  STEP  2 
□RUN  GFX2("CURXY" , 0 ,T) 
□RUN  GFX2t"ERLINE") 
□NEXT  T 

□RUN  GFX2C"CDL0R",3,2) 
□END 
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FILL  Fill  (paint)  window 


Syntax:    RUN  GFS2([pmmil*^MiJL%[3e(m'i^c^ 

Function:  Paints  an  area  with  the  current  foreground  color. 
Paint  fills  the  portion  of  the  window  that  is  the  same  color  as 
the  pixel  under  the  draw  pointer. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

use  the  FILL  fiinction. 

xcorjcor  Are  optional  X-  ani  Y-coordinates  to  reposi- 
tion the  draw  pointer  before  FILL  begins.  If 
you  omit  these  coordinates,  BASIC09  uses  the 
curr^t  draw  position. 

Examples: 

RUN  GFX2("F ILL" ,100,100) 

Sample  Program: 

This  procedure  draws  and  fills  100  bo^s  on  a  window. 

PROCEDURE  colorbox 

ODIM  A  ,B,C,D, T, COLOR: INTEGER 

□COLDR=0 

QRUN  GFX2C"CLEAR") 
DFOR  T-1   TO  100 

aPi=RND(5e0) 

□B  =  RND(1 51  ) 

□C=A+RNDC80) 

aD=B+RND(40) 

□C0LDR«CaLDR+1 

□RUN  GFX2("C0LDR" , COLOR) 

□RUN  GFX2C"BDX",A,B,C,D) 

DRUM  GFX2<"FILL",fi+1 ,B+1 ) 

□NEXT  T 
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FONT  Define  font  buffor 


Syntasc!    KDN  mmifim,FVOmT',group,btmt) 

Function:  Defines  a  buffer  from  which  BASIC09  gets  the  char- 
acter font  (style)  for  the  current  screen.  Use  the  text/cursor 
handling  fttnetiofts  referenced  in  tWs  seiCtfon  with  the  font  ytiu 

load.  When  you  merge  the  Stdfonts  file  in  your  SYS  directory 
with  a  graphics  window,  you  have  the  choice  of  three  fonts 
from  Buffers  1,  2,  and  3,  located  in  Group  200.  You  can  also 
(atmte  your  own  fonts.  FONT  works  only  on  graphics  screen. 
Sfee  "Using  Fonts"  earlier  in  this  chaptar. 

l&m  must  load  t>nt  ym  wmxt  to  tm  into  t&e  ^fiei  Mir 
before  using  FOKfT. 

path  The  route  to  ishe  window  in  ^ch  you  want  to 

use  an  alternate  font. 

group  The  group  number  of  the  buiBfer  containing  the 

font  to  use. 

buffer  The  number  of  the  buffer  containing  the  font 

to  use. 

Examples: 

RUN  GFX2("FONT",200  ,2) 
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GCSET  Set  ^aphics  cursor 


Syntax:     RUN  GFX2("GCSET",g^roup,  buffer) 

Function:  Defines  a  buffer  from  which  BAilCfiS  gels  thti 
graphics  cursor.  This  lets  you  define  your  own  cursor  i» 
graphics  operations.  To  turn  the  graphics  cursor  off,  use  a 
group  Number  0.  You  must  execute  this  command  to  display  a 
graphics  cursor.  Before  using  GCSET,  you  must  merge  the 
Stdcur  file  in  the  SYS  directory  to  the  wkidow. 

Parameters: 

group  The  group  number  of  the  buffer  containing  the 

cursor  image  to  use.  See  OS-9  Windowing 
System  for  information  on  the  group  to  use. 

bi^er  The  number  of  the  buffer  that  contains  the 

cursor  image  to  use.  See  OS-9  Windowing 
System  for  information  on  the  buffer  to  use. 

Examples: 

RUN  GFX2("GCSET" ,1,5) 
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GET 


Get  a  Moek  from  the  window 


Syntax:     RUN  GFX2([paihJ"GET",gj-oup,buffer,xcor, 


Function:  Saves  a  window  area  Get/Put  buffer.  Use  PUT  to 
replace  the  image  to  the  window.  If  you  did  not  previously 
define  the  buffer,  BASIC09  creates  it.  If  you  store  the  window 
data  in  a  predefined  buffer,  the  data  must  be  the  same  size  or 
smalkr  tlian  ibe  bu£^.  If  not,  WiBL&B  tnxaeates  tibe  liata  to 
the  size  rfthe  buffer.  (Also  see  PUT  and  DEFBUFF.) 


Parameters: 


buffer 
occor,ycor 


xsize 


ysize 


The  route  to  ^  mixSim  wfai^  ym  want  to 
a$m  an  image. 

The         numte  <i  iks  Get  bufifer  (1-199)  . 
Ilii  Gel  Mir  mmkm  (l-2iS)  . 

The  X-  and  Y-coordinates  of  the  upper  left  cor- 
ner of  the  window  image  to  save.  The  X- 
coordinates  are  in  the  range  0-639.  The  Y- 
coordinates  are  in  the  range  0-191. 

The  horizontal  size  of  the  window  section  to 
save. 

The  va^ieal  size  of  i^bst  window  sectssn  to  ^Eve. 


Examples: 

RUN  GFX2{"GET",1  ,5,0,0,10,15) 
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Sample  Program: 

This  procedure  draws  a  character,  loads  it  into  a  buffer,  then 
repeatedly  replaces  the  character  to  the  window  screen  using 
PUT.  Each  new  image  erases  the  previous  image,  giving  an 
impression  (tf  antoatei. 

PR'DCEIJURE  puttdown 

□DIM  T, J: INTEGER 

□RUN  GFX2C"CLEAR") 

□RUN  GFX2C "ELL  IPSE", 320 ,96,1 2,4) 

□RUN  GFX2("CIRCLE",320 ,90 ,5) 

□RUN  GFX2C"CDL0R",1 ) 

□RUN  GFX2C"FIL L " , 320 , 96 ) 

□RUN  GFX2C"CDL0R",3:) 

OR  t/N  ®  F  K  a  <  M  F  f  L  L  w ,  32  0  , 9  r> 

□RUN  GFX2("BAR" ,305,1  00,  335 ,1  04) 

□RUN  GFX2C"GET",1 ,1 ,288,85,50,23) 

□  RUN  GFX2C"GET",1  ,2,1  ,1  ,50,23) 

□RUN  GFX2C"PUT",1 ,2,288,85) 

nJ=1  0 

□FDR  T=20  TQ  559  STEP  6 

□J=J+2 

□RUN  GFX2("PUT",1 ,1 ,T, J) 
□NEXT  T 

DRUN  ©F X2C I LLBUFF", 1 , 1 ) 
□RUN  GFX2C"eURDN") 

□END 
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GPLOAD  Load  data  into  Get/Put  buffer 


Syntax:     RUN  GFX2i"GPhOAD'%group,buffer,fyrmat, 
xdim,ydim,size) 


Function:  Loads  a  buffer  with  image  data  that  PUTBLK  can 
use  for  window  displays.  If  the  Get/Put  buffer  is  not  created, 
BASIC09  creates  it.  If  it  is  defined,  the  size  of  the  data  should 
nOt  Be  larger  than  the  buffer. 


Parameters: 

group 

buffer 
fbrnrnt 
xdim 
ydim 

Examidep 


The  group  number  you  select,  in  the  range  1- 
199,  to  let  you  group  buffers. 

A  number  in  tti  wasfe  that  you  assign 
to  the  buffer  you  create. 

The  type  code  of  the  sGreen  format.  (See  Table 
9.4.) 

The  X  (horizontal)  dimension  of  the  stored 
block. 

The  Y  (vertical)  dimension  of  the  stored  block. 

The  size  of  the  buffer  in  bytes.  A  buffer  size 
can  be  in  the  range  of  1  to  8  kilobytes, 
depending  on  available  memory. 


iUN  GFX2C"DEFBUFF",1 ,5,06,100,50,5000) 
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INSLIN  Insert  line 


%ntax:     RUN  GFX2([pati!iJ«mSLIN") 

Function:  Moves  the  window  lines  at  and  below  tlau  carisor 
down  one  line. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  a 

blank  line. 

Examples: 

RUN  GFX2(" INSLIN") 

Sample  Program; 

This  procedure  draws  a  itnind  &e#  m  the  'mrmsi,  theK  tts» 
INSLIN  and  DELLIN  to  make  a  mouth  appear  to  move. 

PROCEDURE  chomp 

□DIM  X  ,  Y  ,T:  INTEGER 

DD I M  R  ESPQ8SE : SIR  I NG  C 1  J 

□RESPONSE="" 

□RUN  GFX2C"CLEAR") 

□  RUN  GFX2 ( "CI RCLE"  ,  32  0 ,96,80) 
□RUN  GFX2C"CQLDR",0,2) 

ORUN  GFX2C»'PILL«',32i5,9G) 
□RUN  GFX2("C0LDR"  ,  2) 
□RUN  GFX2("CIRCLE",285,80,12) 
□RUN  GFX2C"CIRCLE",355,80,12) 
□RUN  GFX2("FILL",285,80) 
□RUN  GFX2C"FILL",355,80) 
□RUN  GFX2("CIRCLE",31B,9G,3) 
□RUN  GFX2("CIRCLE",325,96,3) 

□  RUN  GFX2C"ARC",320 ,92,1  4,3,3, 1  ,1  ,1  ) 
□RUN  GFX2("CDL0R",3,2) 

□RUN  GFX2("CIRCLE",289,77,3) 
□RUN  GFX2("CIRCLE",359,77,3) 
□RUN  GFX2C"CURXY" , 0 , 1 4) 
□REPEAT 
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DRUN  GFX2C"INSLIN") 
DFOR  X=1   TO  100 

□NEXT  X 

DRUN  GFX2("DELLIN") 
□RUN  INKEYCRESPGNSE) 
□UNTIL  RESPONSE)"" 
□END 
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KILLBUFF  Deallocate  Get/Put  buffer 


^tax:     RUN  GFX2("KILLBUFF",^u|%&Bfifei^ 

Deallocates  the  indicated  Cret^*ut  buffer.  Y(m  select  group  and 
buffer  numbers  when  you  define  a  buffer  or  when  you  load  or 
get  a  window  image.  For  more  information  on  Get/Put  buffers, 
see  DEPBUPF,  PUT,  GET,  amd  tlH/<mD. 

Parameters: 

group  The  group  number  of  the  buffer       want  to 

deallocate,  in  the  range  1-109.  BufiENf  Group 
Numbers  0  and  200-255  are  reserved  for  OS-9 

system  use. 

buffer  The  number  of  the  buffer  to  deallocate,  in  the 

range  1-255. 

Examples: 

RUN  GFX2C"KILLBUFF",1 ,51 

Sample  Program: 

This  procedure  draws  a  figure  on  a  window  screen,  loads  it 
into  a  buffer,  then  repeatedly  places  it  in  new  locations  on  the 
screeai.  Each  new  PUT  erases  the  previous  image. 

PROCEDURE  put down 

□DIM  X,Y,T, J: INTEGER 

□RUN  GFX2C"CURDFF") 

DRUM  GFX2<"CLEAR") 

□RUN  GFX2C"ELL IPSE", 320 ,96,1  2,4) 

ORUM  GFX2f "C I RCLE" , 320 , 90 , SJ 

□RUN  GFX2C"C0L0R",1 ) 

□RUN  GFX2C"FILL",320 ,9G) 

□RUN  GFX2("CDL0R",3) 

□RUN  GFX2C"FILL",320,90) 

□RUN  GFX2C"BAR" ,305 , 1 00 ,335 ,104) 

□RUN  GFX2("GET",1 ,1 ,288,85,50,23) 

□RUN  GFX2("GET",1 ,2,1 ,1 ,50,23) 

□RUN  GfX2("PUT",1 ,2,288,85) 


9-101 


BASIC09  Reference 


aj»i0 

QFOR  T=20  Td  559  STEP  6 

DJ=J+2 

ORUN  GFX2C"PUT",1 ,1 ,T, J) 
DNCXT  T 

DRUN  GFX2C"KILLBUFF"M  ,1  ) 

DRUN  GFXaC'CURQN") 

□END 
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LINE  Draw  a  line 


Syntax:     RUN  GFX2i[path,Y'hlNE"[,xcorl,ycorl],xcor2, 
ytnn-2) 


Function:  Draws  a  line  in  one  of  the  following  ways: 

•  Wram      eurrent  draw  pointer  to  the  specified  X-  and  Y- 

•  Frcnn  tibe  specified  beginning  X-  and  Y-coordinates  to 
the  specified  ending  X-  and  Y-coordinates. 

Parametersf 

paih  The  route  to  the  wiffliftow  in  which  you  want  to 

draw  a  line. 

xcorl^orl      The  optional  beginning  X-  and  Y-coordinates 

for  the  line. 

xcor2,ycor2       The  ending  X-  and  Y-coordinates  for  the  line. 
Examples; 

RUN  GFX2C"LINE",192,128) 
RUN  GFX2C"LINE",0,0,192,128) 

Sample  Program: 

This  procedure  draws  a  sine  wave  e£  v&clacal  lines  across  a 
window. 

PROCEDURE  waves 
□DIM  A,X,Y,Z: INTEGER 
OCALC-0 
□A=1 00 

ORUN  GFX2("CLEAR") 
□RUN  GFX2C"C0LDR",3,2) 
OFOR  )«  =  0  TO  638  STEP  1 
□CALC=CALC+ . 05 
□Y=A-SINCCALC)»1 5 
0Z-Y+2S 
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DRUM  GFX2("LINE",X,Y,X,Z) 

□NEXT  X 

OEND 
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LOGIC  Perform  logic 


LCtion 


Syntax:     RUN  GFX2("L0aiC","^e«aii") 

Function:  Causes  BASIC09  to  perform  the  specified  logic  func- 
tion on  all  data  bits  used  by  subsequent  drawing  functions. 
Once  set,  the  logic  function  remains  in  effect  until  you  turn 
LOGIC  off. 

Parameters: 

function  can  be  one  of  the  following  logical  functions: 


RUN  GFX2("L0GIC","AND") 
RUN  GFX2("L0GIC","XDR") 

Sample  Program: 

This  procedure  uses  LOGIC  to  draw  a  horizontal  bar  across  a 
background  of  multicolored  vertical  bars.  Using  XOR  logic,  the 
procedure  causes  the  horizontal  bar  to  change  the  color  of  each 

vertical  bar. 

PROCEDURE  logic 
□DIM  A, Z,T,X,Y,CDLDR: INTEGER 
□RUN  GFX2("L0GIC","0FF") 
□RUN  GFX2<"CLEAR") 

□CDLDR=0 

□FDR  T=0   TD  ei9  STEP  20 

□CDLDR=CDLDR+1 

ORUN  GFX2<"CDLDR", COLOR) 

□RUN  GFX2C'«BAR",T,0  ,1  +  20,190) 

□NEXT  T 

□RUN  GFX2("CaL0R",3,2) 
□RUN  GFX2CLDGI  C","XOR") 


OFF  —  no  logic 

AND  —  performs  AND  logic 

(M  —  performs  OR  logic 

XOR  —  performs  XOR  logic 


BASIC09  Reference 


□FDR  T=1   TD  10 

□RUN  GFX2C"BAR", 0,80, 839,1 12) 

□NEXT  T 

□RUN  GFX2C"L0GIC","0FF") 
DEHD 
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OWSET  Establish  an  overlay  window 


Syntax:     Wm  GFX2([path,]"OWSET",save  switch,xpos, 
ypo8,xsize,yaize,foreground,background) 


Function:  Creates  an  overlay  window  on  a  previously  existing 
device  •mx^sm.  Wimws&gwe&  tihe  cstrrert  device  window  paths 
to  use  a  new  area  of  the  screen  as  tiie  eurrent  device  window. 


Parameters: 

path 

save  switch 


xpos 

ypos 

xsize 
ysize 

foreground 
background 


The  route  to  the  window  in  which  you  want  to 

set  an  overlay. 

Either  0  or  1.  A  value  of  0  teUs  BASIC09  not 
to  save  the  overlaid  area.  A  value  of  1  tells 
BASIC09  to  save  the  overlaid  area  and  restore 

it  when  the  new  window  closes. 

The  character  column  in  which  to  start  the 
new  window  (upper  Irft  comer). 

The  character  row  in  which  to  start  the  new 
window  (upper  left  comer). 

The  width  of  the  new  window  in  characters. 

The  depth  of  the  new  window  in  rows. 

The  foreground  color  of  the  new  window. 

The  background  color  of  the  new  window. 


Examples: 

RUN  GFX2C-DWSET" , 00 , 44 , 1 0 , 32 ,8 , 00 , 06) 

Sample  Program: 

This  procedure  creates  six  progressively  smaller  overlay  win- 
dows, labeling  each.  It  then  waits  for  you  to  press  a  key,  after 
which  it  erases  all  the  windows  and  leaves  the  original  window 
intact. 
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PROCEDURE  overwin 

□DIM  f,Y,5f1  ,t1  ,TjJ,l,U,FLACE:  INTEGER 

□DIM  RESPDNSE:STRINGE1 ] 

□X=0  \Y=0 

□X1=80  \Y1=24 

PR LACE =33 

□FOR  T=1  TO  6 

□IF  T=2  OR  T=6  THEN 

□B  =  3 

□ELSE  B=2 
□END  IF 

□RON  GFl^C'OWSET" ,1,X,Y,X1,Y1,B,T) 
□X=X+e  \Y=Y+2 
□X1=X1-12  \Y1=Yl-4 
tJFiR  J«1  to  S 

□PRINT  TABCPLACE);  "Over lay  Screen  "5  T 

□NEXT  J 

□PLACE=PLACE-e 
□NEXT  T 

□PRINT  "Press  fi  Key.,,"? 

□GET  #1 .RESPONSE 

□FDR  T=1    TO  8 

□RUM  GFX2C"0WEND"J 

□NEXT  T 

□END 
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PALETTE  Set  color  for  palette  registers 


Syntax!    RUN  GfXlCIiiafl^Fmi^TTE'Sregister,caror) 


Function:  Sets  palette  colors.  Lets  you  install  any  of  the  Color 
Computer's  64  colors  in  the  palette  for  use  with  text  and 
graphics. 


Parameters: 

path 

register 
eohr 


The  route  to  the  window  where  you  want  to 
change  palette  Gok>rs. 

The  number  of  the  register  in  which  you  want 
to  install  a  new  color. 

The  code  of  the  new  color  you  want  to  install. 


RUN  GFX2("PALETTE:*Mi,32) 


Sample  Program: 

This  procedure  draws  a  series  of  bars  and  circles,  then  repeat- 
edly ehmgm  their  colors  using  B\.LETTE. 

PROCEDURE  palette 

□DIM  T,K, J, X ,Y, COLOR: INTEGER 

□DIM  RESPDNSE:STRING[1 ] 

□RUN  GFX2C"CDL0R",3,2,2) 

□CDLDR=0 

□RUN  GFX2("CLEAR") 

□RUN  GFX2C"CURDFF") 

□FOR   Y=0   TO  23  STEP  3 

□  RUN  GFX2C"C0L0R"  ,  COLOR) 

□RUN  GFX2("BAR",0,Y,G39,Y+3) 

OCDLOR=COL0R+1 

□IF   C0L0R=2  THEN 

□COLOR=COL0R+1 

□ENDIF 

□NEXT  Y 

□FOR  Y=164  TO  185  STEP  3 
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□RUN  GFX2("CDLaR",COL0R) 

□RUN  GFX2("BAR",fl,Y,639,Y+3) 

□CDL0R=CDL0R+1 

□NEXT  Y 

nCOLDR=f 

□FDR  K=45  TO   170   STEP  48 

□FDR  T=1 00   TO  580   STEP   1 00 

□RUN  GFX2("CDLDR" , 3) 

□RUN  OFX2<"CIRCLE",T,K,30> 

□R UN  GF  X 2 C "COL OR » , Q OLORl 

□RUN  GFX2C"FILL",T,K) 

□CDLDR=CDLDR+1 

□IF  CaLaR=2  THEN 

DCDLDR=C0L0R*1 

DENDIF 

□NEXT  T 

□NEXT  K 

ORIPEAT 

0X=RNDC63> 

□REPEAT 

□Y=RND(1S)+1 

□UNTIL  Y<>2 

□RUN  G F X 2 ( "P A L ETTE " , Y , X ) 
□RUN  INKEY(RESPDNSE) 
□UNTIL  RESPONSE)"" 
□RUN  GFX2("DEFCDL") 
□RUN  GFX2C"CURDN") 
□END 
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PATTERN  Select  pattern  buffer 


Syntax:     RUN  GITC2([jj®«ft,]"PATTERN'',groHp,iba£fer) 


Function:  Selects  the  contents  of  a  preloaded  Get/Put  buffer  as 
a  pattern  for  graphics  functions.  Although  PATTERN  can  use 
a  buffer  of  any  size,  it  uses  a  specific  number  of  bytes,  ^p^id- 
ing  on  the  screen  format  in  use: 


Color        Pattern  Bits 
Mode        Array  Size  Pea?  PfiJ 


02  4  bytes  x  8  bytes  =  32  bytes  1 

04  8  bytes  x  8  bytes  =  64  bytes  2 

16         16  bytes  x  8  l^s  =  128  l^es  4 


The  pattern  array  is  a  32  x  8  pel  representation  of  graphics 
memory.  It  takes  the  current  color  mode  into  consideration  to 
define  the  number  of  bits  per  pel  and  pels  per  byte.  If  the 
buffer  is  larger  than  the  number  of  bytes  required,  PATTERN 
ignores  the  estm  %tes.  BAg[C09  uses  the  8e3:ected  pattmi 
with  all  draw  commands  until  you  change  the  pattern  or  turn 
off  the  pattern  function  by  specifying  a  group  and  buffer  num- 
ber of  0. 


Parameters: 

path 

group 

buffer 


The  route  to  the  window  in  which  you  want  to 
use  a  new  graphics  pattern. 

The  group  number  of  the  buffer  you  want  to 

use  for  a  graphics  pattern. 

The  buifer  number  that  you  want  to  use  for  a 
I  plttera. 


Examples: 

RUN  GFX2C"PATTERN",1  ,3) 
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Sample  Pro-am: 

This  procedure  loads  the  current  window  data  at  location  0,0 
into  a  buffer  to  use  as  a  draw  pattern.  It  then  draws  a  circle  and 
fills  the  circle  with  the  pattern  in  the  buffer. 

PROCEDURE  pattern 

DDIM  X,Y,T: INTEGER 

DRUN  Gf  X'2  t*'SErT" ,  1  , 1  , 0 ,  t ,  S ,  i  ) 

□RUN  GFX2C"CDLDR" ,4) 

□RUN  GFX2("CLEAR") 

□RUN  GFX2C"C I RCLE" , 320 ,96,1fl0) 

□RUN  GFX2("FILL",320 ,96) 

□RUN  GFX2 C«P ATTERN" ,1,1) 

□RUN  GFX2C"C0LDR" ,3) 

□RUN  GFX2C"FILL",320,96) 

□RUN  GFX2C"PATTERN",0,0) 

□END 
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POINT  Mark  a  point 


Syntax:     RUN  GFX2([pat&,]"POINT"[,xGor,jcor]) 


Function:  Sets  the  pixel  at  the  current  draw  pointer  position 
or  at  the  specified  coordinates  to  the  current  foreground  color. 
If  you  do  not  specify  coordioates,  POINT  sets  the  pixel  at  the 
draw  pointer. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

turn  on  the  specified  pixels. 

xcor^cor         Optional  coordinates  for  the  POINT  function. 

The  X-eocnrdinates  are  in  tlw  range  0>'@39.  Hie 
Y-coordinates  are  in  the  range  0-191. 

Examples: 

iUN  6FX2C«P0IMT") 

RUN  GrxaCPQINT" ,  1 92 , 1  ti) 

Sample  Program: 

This  procedure  uses  POINT  to  produce  a  swirl  design  on  a  win- 
dow screen. 

PROCEDURE  point 

□BASE  0 

□DIM   X{2B)  ,Y(20)  :  INTEGER 
□DIM  T, R, J, K: INTEGER 
□J  =  0 
□K  =  0 

□RUN  GFX2("CURQFF") 
□RUN  GFX2("CLEAR") 
□FDR  T=1   TO  288  STEP  3 

nj=j+i 

OF OR  R=0  TO  11 

□X(R)=INT(T»SIN(30»R+K))+32  0 
□Y(R)=INT(J»COS(30*R+K))+96 
DRUN  GF X 2( "PO I  NT" , X  t  R ) , YCR ) ) 
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□K=K+1 
□NEXT  R 

□NEXT  T 

□RUN  GFX2("CURDN") 
□END 
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PROPSW  Proportional  space  switch 


Syntax:     RUN  GFX2([patfi,]"PR0PSW","swf<«ifi") 

Function:  Enables  or  disables  the  automatic  pr<q)ortional  spac- 
ing of  characters  on  graphic  screens. 

Parameters: 

path  The  route  to  the  window  in  which  you  want  to 

use  proportional  character  spacing. 

switch  Either  OFF  to  turn  proportional  spacing  off,  or 

ON  to  turn  proportional  spacing  on.  The 
default  setting  of  the  switch  is  OFF. 

Examples: 

RUN  GFX2C"PRDPSW","DN") 
Sample  Program: 

This  procedure  produces  a  demonstration  of  the  BASIC09  propor- 
tional sp£icing  function. 

PROGEDQiE  prepsrt 
DDIM  LI  HE: STRING 
□DIM  LETTER:STRINGt1 1 
DDIM  T, J, K, FLAG: INTEGER 
□RUN  GFX2("CLEAR") 
□FLftG-l 

OFOR  T=1   TO  12 
□READ  LINE 

□FDR   J=1    TD  LENCLINE) 

□LETTER=MID$(LINE, J,1 ) 

□  ir  LETTERO"!"  AND  LETTER<>"#"  THEN 

□PRINT  LETTER; 

□ENDIF 

JIF  LETTER="!"  THEN 

DFLAG=FLAG«-1 

nir  FLfiG^B  THEN 

□RUN  GFX2("PR0PSW","0FF"j 
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□ELSE 

mm  GF)(2<"PR0PSW","aN") 

□ENDIF 
□ENDIF 

□IF  LETTER="#"  THEN 
DPRINT  CHR$(34); 
DENDIF 

□NEXT  J 
□PRINT 
□NEXT  T 

DPRINT  \  PRINT 
QEND 

□DATA  "This    is  a  demonstration  of" 
□DATA  "! Proper t ional  Spacing!  using" 
□DATA  "BASIC09's  GFX2  module." 
□DATA 

□DATA  "IThe  qulcfe  brawn  fox  jumped...!" 
□DATA  "The  quick  brown  fox  jumped..." 
□DATA  "" 

nOATft  "Use  the  conmswid" 

□DATA  "!RUN  GFX2(  iCPROPSW*  ,  #DN#)  !  " 

□DATA  "to  turn  proportional  spacing  on." 

□DATA  "Use    !  RUN  GF X 2 (  #PRQPSUI#  ,  #OFF#  )  !  " 

□DATA  "to  turn  proportional  spacing  off" 
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PUT 


Put  a  saved  data  block  on  the  window 


^tax:     RUN  GF^i[pam;i^*PXfl^,0emp,Bsia^i 
xcor,yco^ 


Function:  Places  the  linage  in  the  specified  Get/Put  buffer  on 
the  window.  PUT  f equires  only  the  group  and  buffer  numbers 
and  the  window  coordinates  for  the  upper  left  corner  of  the 
image.  The  GET  function  saves  the  dimensions  of  the  block  in 
the  buffer.  PUT  automatically  handles  window  format 
conversion. 


Parameters: 

path 

group 
buffer 
xcorjcor 


The  imtfe  to  the  window  where  you  want  to 
place  a  pre-sa^d  image. 

The  group  number  of  the  buffer  in  which  to 
save  the  window  data. 

The  buffer  number  in  which  to  save  the  win- 
dow data. 

The  X-  and  Y-coordinates  of  the  upper  left  cor- 
ner of  the  window  position.  The  X-coordinates 
are  in  the  range  0-689.  The  Y-coordinates  are 
in  the  range  0-191. 


Examples: 

RUN  GFX2C"PUT",1 ,5,1 00,B0) 
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Sample  Program: 

This  procedure  draws  a  character,  loads  it  into  a  buffer,  then 
repeatedly  replaces  the  character  to  the  wjaSov?  SJJteaEi  tising 
PUT.  Each  new  image  erases  the  {o-evious  image,  giving  an 

impression  of  animation. 

PROCEDURE  putdown 

nDIH  X,Y,T, J: INTEGER 

□RUN  GFXZC'GURDFF") 

□RUN  GFX2C"CLEflR") 

OR  UN  GFX2( "ELL  IPSE", 32  0 ,96,1  2,4) 

□RUN  GFX2<"CIRCLE",320,90,5) 

□RUH  0FXt<"CDLDR*M  ) 

□RUN  GFX2("FILL",320,96) 

□RUN  GFX2C"CaL0R",3) 

DRUN  GFX2C"FILL",320,90) 

□RUN  GFX2< "BAR", 305,1 00 ,335,1 04) 

□RUN  GFX2("GET",1 ,1 ,288,85,50,23) 

□RUN  GFX2("GET",1 ,2,1 ,1 ,50,23) 

□RUN  GFX2C"PUT",1  ,2,288,85) 

□  J  =  1  0 

□FDR  T=20  TD  559  STEP  G 
0J=J+2 

□RUN  GFX2("PUT",1 ,1 ,T,J) 

□NEXT  T 

DiUN  ©FX2("KILLBUFF",1  ,1) 
□RUN  GFX2C"CUR0N") 

□END 
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PUTGC  Put  i^pMcs  cursor 


Syntax:     RUN  GFX2([paih,]"POTaC",xcor,ycar) 


Function:  Places  and  displays  the  graphics  cursor  at  the  speci- 
fied bcation.  Use  screm  relative  coordinates  for  this  function, 
not  window  relatiire  coordinates.  The  hOTizontal  ranfe  is 
0-639.  The  vertical  range  is  0-191. 

Farameters: 

path  The  roate  to  the  wiaiow  whare  yoa  want  to 

display  a  graphics  cursor. 

xcor,ycor  The  screen  coordinates  for  the  cursor  location. 

The  X  coordinates  are  in  the  range  0-639.  The 
Y  coordinates  are  in  the  range  0-191. 

Examples: 

RUN  GFX2C"PUTGC",100,5) 

Sample  Program: 

This  procedure  displays  the  available  graphic  cursors  stored  in 
group  202.  Before  this  procedure  can  work,  you  must  merge  the 
Stdptra  file  in  the  SYS  directory  of  your  system  disk  with  the 
window  you  are  using.  For  instance,  if  your  system  diskette  is  in 
Drive  /DO,  merge  Stdptrs  with  Window  1,  by  typing: 

merge  /d0/sys/atdptf  a  >  /w1  |  ENTER  | 

PROCEDURE  vlewcur 

DDIM  T ,Z :  INTEGER 

□RUN  GFX2C"CLEAR") 

□FDR  T=1    TO  7 

□RUN  GFX2C"QCSET",20  2,T) 

□RUN  GFX2('»:pUT©C",320,96) 

□FOR  Z=1    TO  6000 

□NEXT  Z 

□NEXT  T 

DRUN  GFX2<"GCSET",0,0) 

□END 
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RE  VON  Reverse  video  on 
REVOFF  Reverse  video  off 

^tax:    mm  6FX2(IiMi£fa,]''REVON'0 
RUN  GPX2(Iiia<a,]"RlVOFF") 

Function:  Enables  or  disables  reverse  video  characters.  Once 
set,  reverse  video  remains  in  effect  until  you  execute  the 
reverse  video  off  function. 

Barometers: 

paih  'The  route  to  &e  ^dndow  in  which  you  want  to 

display  reverse  characters. 

Ex^JOiplesi 

ION  €F){2f»REVQt") 
RUN  GFX2t"REVDFF") 


9-120 


Displaying  Text  and  Graphics  I  9 


SCALESW  Enable/disable  scaling 


Syntax;     RUN  GFX2([pa<li,]"SCALESW","switeli") 

Function:  Enables  or  disables  scaling  when  drawing  on  var- 
iously formatted  windows.  Scaling  in  windows  is  normally  on. 
If  scaling  is  off,  coordinates  are  relative  to  the  window  origin 
coordinates.  Scaling  does  not  affect  text. 

Paramef^s: 

path  The  route  to  the  window  vibeace  you  want  to 

turn  scaling  off  or  on. 

switch  Either  OFF  (disable  scaling)  or  ON  (enable 

scaling). 

Examples: 

RUN  GFX2("SCALESW","0FF") 

Sample  Program: 

This  procedure  runs  a  routine  of  drawing  a  design  in  overlay 
windows  twice.  The  routine  runs  once  vdth  scaling  off  and  once 
with  scaling  on.  Aft@r  the  first  routine  pauses,  press  the  space 
bar  to  see  the  second  demonstration. 

PROCEDURE  scale 

□DIM  X,Y,X1,Y1,T,B,J,R,W,Z: INTEGER 
□DIM  RESPONSE : STRINGC1 ] 
DRUN  GFX2C"CLEAR"> 
OFOR  J-1   TO  2 

□IF  J=1  THEN 

□RUN  GFX2C"SCALESW  ,  "OFF") 
□  ELSE 

□RUN  GFX2C"SCALESW","0N") 
OENDIF 

□X=0   \Y=0   \X1=80  \Y1=24 
□FDR  T=1    TD  4 
□IF  T=2  OR  T=6  THEN 
□B  =  3 
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□ELSE  B=2 

rmmf 

□RUN  GFX2("DWSET",1 ,X,Y,X1 ,Y1 ,B,T3 

□FDR  R=1    TO  35 

□W=40»SIN(R)+1 70 

□Z=25»C0S(R)+45 

DRUM  GFX2("CIRCLE",W,Z,30) 

□NEXT  R 

□  X  =  X  +  G  \Y  =  Y  +  2   \X1=X1-12   \Y1  =Y1 -4 
□NEXT  T 

□PRINT  "Press  A  Key. . ."; 
D6ET  #1 , RESPONSE 

□FOR  T=1    TO  4 
□RUN  GFX2("DWEND") 
□NEXT  T 
□NEXT  J 
□END 
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SELECT  Select  next  window 


Syntax:     RUN  GFX2([iiaa],"SELECT'') 

Function:  SELECT  causes  a  window  to  display  if  the  proce- 
dure is  operating  in  the  active  window.  If  the  procedure  is  not 
in  the  active  window,  the  newly  selected  window  displays 
when  you  press  I  clear  |.  If  you  do  not  specify  a  path,  BASIC09 
sdects  the  device  using  the  standard  input,  standard  output, 
and  standard  error  paths,  Paths  0,  1,  and  2. 

path  The  path  to  the  window  to  select. 

Examples: 

RUN  GFX2("SELECT") 
RUN  GFX2(1 ."SELECT") 
RUN  GFX2CPATH, "SELECT") 

Sample  Program: 

From  /TERM,  this  procedure  temporarily  opens  a  path  to 
Window  3,  creates  the  window  format,  and  uses  SELECT  to  dis- 
play the  new  window.  It  draws  a  design,  then  returns  to  the 
/TERM  screen  and  closes  the  path. 

PROCEDURE  design 
□DIM  PATH,T,Y: INTEGER 
DDPEN  #PATH,"/N3":WRITE 

ORUN  GFX2CPATH,"DWSET", 5, 0,0 ,80 ,24,3,2,2) 
□RUN  GFX2CPATH , "SELECT") 

□  Y=1 

□FDR  T=1    TD   200   STEP  3 
□Y= Y+ 1 

□RUN  GFX2CPATH,"ELLIPSE",320 ,96,T, Y) 
□NEXT  T 

□RUN  GFX2(PATH , "COLOR" , 1 , 2) 

□FDR  T=200  TD   1    STEP  -6 

ORUN  GFX2tPATH, "ELLIPSE", 320, 96, T,Y) 
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□IF   INTCT/3)=T/3  THEN 

□Y=Y+1 

□ENDIF 

ONEXT  T 

□RUN  GFX2(1 , "SELECT") 
□RUN  GFX2(PATH,"DWEND") 
□CLOSE  #PATH 
□END 
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SETDPTR  Set  draiir  pointer 


Syntajf:     WM  GFX2([pa*h,]«SETDPTR",xcor,ycor) 

Functioii:  Places  the  draw  pointer  at  the  specified  coordinates. 
The  draw  pointer  selects  the  beginmng  point  of  the  next 
graphics  draw  function  tsmh  as  CfilCLE,  LINE,  BOX,  and  so 
on),  if  you  do  not  supply  other  cocn'dinates. 

P^ameters: 

path  The  route  to  the  sereea  whm  ym  mnt  to  set 

the  draw  pointer. 

xcor^cor  The  screen  coordinates  for  the  draw  pointer 

location.  The  X-coordinates  are  in  the  range 
0-639.  The  Y-coordinates  are  in  tiie  range  0- 
191. 

Examples: 

RUN  GFX2C"SETDPTR",1 00,5) 
Sample  Program: 

This  procedure  uses  coordinates  from  a  DATA  statement  for  set- 
ting tiie  draw  pointer  to  create  a  series  of  star  shapes. 

PROCEDURE  star 
ODIM  X,Y,T, J: INTEGER 
DPtINT  CHR*C12> 
□FOR  J=1   TO  10 
□READ  X,Y 

□RUN  GFX2C"SETDPTR",X+J,Y+J+J) 
OFDR  T=1  TO  5 
OREAD  X,Y 

□RUN  GFX2("LINE",X+J, Y+J+J) 
□NEXT  T 
DNEXT  J 

ODATA  320,46,440,146,200,84,440,84,20  0,1 46,320,46 

DEND 
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Underline  characters  on 
UNDLNOFF  Underline  characters  off 

Syntax:     RUN  GFX2([pai/i,]"UNDLN0N") 
RUN  GFX2([|Mi«i,]"UNDLN0FF") 

Function:  Enables  or  disables  character  underline.  After  you 
execute  UNDLNON,  all  characters  displayed  are  underlined 
until  you  execute  UNDLNOFF.  The  default  is  UNDLNOFF. 

Parameters: 

path  The  route  to  the  window  where  you  want  to 

use  underline  characters. 

Examples: 

RUN  GFX2("UNDLNQN") 
RUN  GFX2<"UNDLNDFF") 
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BASIC09  Quick  Reference 


This  chapter  contains  a  quick  reference  of  all  BASIC09  eom- 
mands,  gtatetnents,  ami  functions.  It  ineluies  eosinaandi  te<  path 
gramming,  editing,  and  debugging,  as  well  as  the  Commands 

mode  commands. 

The  following  chart  lists  all  BASIC09  keywords  that  you  can  use 
in  a  procedure. 

Statements  and  Functions 


Command 


Description 


ABS 
ACS 
ADDR 

AND 

ASC 

ASN 
ATN 
BASE 

BYE 

CHAIN 

CHD 
CRR$ 

CHX 
CLOSE 

COS 


Returns  the  absolute  value  of  a  number. 

Calculates  the  arccosine  of  a  number. 

Returns  an  integer  value  which  is  the  abso- 
lute memory  addb*e^  oi  a  vartable,  arr^,  or 
structure  in  a  process's  address  space. 

Generates  the  logical  AND  of  two  Boolean 
values. 

Returns  the  ASCII  code  of  the  first  charac> 

ter  in  a  string. 

Calculates  the  arcsine  of  a  number. 

Calculates  the  arctangent  of  a  number. 

Sets  &B  hmst  axita^  m  data  stitiGlip'e  sub- 
script in  a  procedure  to  either  0  or  1. 

Ends  execution  of  a  procedure  and  termi- 
nates BASIC09. 

Executes  a  module,  passing  arguments  if 

appropriate. 

Changes  the  current  data  directory. 

Rettims  the  ASCII  character  represent^ 

a  specified  integer. 

Changes  the  current  execution  directory. 

Deallocates  the  specified  path  to  a  file  or 
device. 

Calculates  the  cosine  of  a  number. 
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Command 


Description 


CREATE  Opens  a  path  and  establishes  a  new  file  on 

disk. 

DATE$  Returns  the  computer's  current  date  and  - 

time. 

DEG  Causes  BASIC09  to  calculate  angles  in 


DATA  Stores  data  in  a  procedure  to  be  accessed 

by  the  READ  statement. 

DELETE  Deletes  a  file  from  disk. 

DIM  Declares  simple  variables,  arrays  or  compile 

data  structure  for  size  and  type. 

DO  See  WHILE/DO/ENDWHILE. 

ELSE  See  IF/THEN/ELSE/ENDIF. 

END  Terminates  execution  of  a  procedure. 

Returns  to  the  calling  procedure  or  to 
BASIC09's  command  mode.  Displays  the 
specified  tmk. 

ENDEXIT  See  EXITIF/ENDEXIT. 

ENDIF  See  IF/THEN/ELSE/ENDIF. 

ENDLOOP  See  LOOP/ENDLOOP. 

ENDWHILE  See  WHILE/DO/ENDWHILE. 

EOF  Tests  for  the  end  of  a  di^  file. 

ERR  Reluas  the  error  code  of  the  most  recent 

error. 

ERROR  Generates  the  specified  error. 

EXITIB'/  Tests  conditions  in  a  loop.  The  procedure 

ENDEXIT  exits  the  loop  if  the  condition  is  true. 

EXP  Calculates  e  (2.71828183)  raised  to  the 

specified  value. 

E^SE  A  Boolean  function  that  always  returns 

FALSE. 

FIX  Rounds  a  real  number  and  converts  it  to  an 

integsr. 

FLOAT  Converts  a  byte  or  integer  value  to  a  real 

number. 
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Command 


Description 


FOR/NEXT 

GET 

GOSUB/ 
RETURN 

IF/THEN/ELSl/ 
ENDIF 


INKEY 

INPUT 

INT 

KILL 

LAND 

LEFT$ 

LEN 
LET 
LNOT 

LOG 

LOGIO 

LOOP/ 
ENDLOOP 

LOR 


Creates  a  program  loop  of  a  specified  num- 
ber of  repetitions. 

Reads  an  element  or  a  data  structure  from 
a  binary  file  or  a  device. 

Transfers  program  control  to  a  specified 
subroutine.  RETURN  sends  execution  back 
to  the  calling  routine. 

Evaluates  an  expression  and  performs  an 
operation  if  the  conditions  are  met.  Includ- 
ing ELSE  causes  an  alternate  operation  if 
the  conditions  are  &lse. 

Stores  the  character  of  a  keypress  in  a 

string  variable. 

Causes  a  procedure  to  accept  input  from 
the  k^board  or  otha-  specified  device. 

Returns  the  largest  whole  numb^  less  than 
or  equal  to  the  specified  value. 

Unlinks  a  procedure.  (Removes  It  from 
BASIC09's  directory.) 

Performs  a  bit-by-bit  logical  AND  on 
two-byte,  or  integer,  values. 

Returns  the  s{>edf!ed  number  characters, 
from  the  leftmost  portion  of  a  string. 

Returns  the  length  of  the  specified  string. 

Assigns  a  value  to  a  variable. 

Performs  a  bit-by-bit  logical  NOT  ftiBction 

on  two-byte,  or  integer,  values. 

Calculates  the  natural  logarithm. 

Calculates  a  base  10  logarithm. 

Establishes  a  loop.  Use  EXITIF  and 
ENDEXIT  to  test  the  loop  and  exit  when  a 

specified  condition  is  true. 

Performs  a  bit-by-bit  logical  OR  on  two- 
byte,  or  integer,  values. 
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Command 


Description 


LXOR 
MID$ 

MOD 

NEXT 
NOT 

ON  ERROR/ 
GOTO 

ON/GOSUB 


ON/GOTO 

OPEN 
OR 

PARAM 
PAUSE 
PEEK 
PI 

POKE 
POS 


Performs  a  bit-by-bit  logical  EXCLUSIVE 
OR  on  two-byte,  or  integer,  values. 

Returns  the  specified  number  of  characters, 
beginning  at  the  specified  position  in  a 
string. 

Returns  the  modulus  (remainder)  of  a  divi- 
sion operation. 

See  FOR/NEXT. 

Returns  tfae  logical  complement  of  a  Boolean 

value. 

Traps  errors  and  transfers  control  to  the 
specified  line  numb^. 

Evaluates  an  expression.  Then,  selects  ftom 
a  list  the  line  number  that  is  in  the  posi- 
tion Indicated  by  the  result  of  the  expres- 
sion. Procedure  execution  transfers  to  the 
selected  line. 

Evaluates  an  expression.  Then,  selects  from 
a  list  the  line  number  that  is  in  the  posi- 
tion indicated  by  the  result  of  the  expres- 
sion. Procedure  execute  jumps  to  the 
selected  line. 

Opens  an  I/O  path  to  an  existing  file  or 
device. 

Performs  a  logical  OR  on  two  Boolean 

values. 

Describes  the  parameters  a  called  proce- 
dure expects  from  a  calling  procedure. 

Suspends  execution  of  a  procedure,  and 
enters  the  Debug  mode. 

Returns  the  byte  value  of  a  memory 
address. 

Represents  the  constant  3.14159265. 

Stores  a  byte  value  at  a  specified  memory 
address. 

Returns  the  current  character  position  of 
the  print  buffer. 
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Command 


Description 


PRINT 

PRINT  USING 

PRINT# 

PRINT#  USING 

PIJT 
RAD 

READ 

REM 

REPEAT/UNTIL 

RESTORE 

RETURN 
RIGHT$ 

RND 

RUN 
SEEK 
SON 
SHELL 

SIN 
SIZE 

m 


Sends  ^Sae  specified  characters  or  values  to 
the  display. 

Sends  characters  or  values  to  the  display, 
using  the  specified  format. 

Sends  the  specified  characters  or  values  to 
the  specified  path. 

Sends  characters  or  values  to  the  specified 
path  using  the  specified  format. 

Writes  data  to  a  random  access  file. 

Causes  BASIC09  to  calculate  angles  in 

radians. 

Accesses  data  from  procedure  DATA  lines  or 
fi?om  files  or  devices. 

Indicates  that  the  following  characters  in  a 
procedure  line  are  comments  and  £ire  not  to 
be  executed.  Also  use  (*        *),  or  (*. 

Establishes  a  loop  that  executes  until  the 

specified  condition  is  met. 

Restores  the  DATA  pointer  to  the  first  data 
item  or  to  a  spedfii^  line. 

See  GOSUB/RETURN. 

Returns  the  number  of  characters  specified, 
from  the  rightmost  portion  of  a  string. 

Returns  a  random  numb^  firom  a  ^^ed 

range. 

Calls  another  procedure  for  execution. 
Changes  the  file  pointer  address. 
Determines  the  sign  of  a  number. 

Calls  an  OS-9  command  or  program  for 

execution. 

Calculates  the  sine  of  a  specified  value. 

Returns  the  number  of  bytes  assigned  to  a 
vaxiable,  afrie^,  m  masj^m.  ^ta  stecture. 

Calculates  a  value  raised  to  the  power  of 
two. 
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Command 


Description 


SQR/SQRT 

STEP 

STOP 

STR$ 

SUBSTRING 

SYSCALL 
TAB 

TAN 
TRIM$ 

TRON/TROFF 

TRUE 

TYPE 

UNTIL 

USING 

VAL 

WHILE/DO/ 
ENDWHILE 

WRITE 
XOR 


Calculates  the  square  root  of  a  positive 
taxsab&c. 

Sets  the  size  of  inca-ement  in  a  FOR/NEXT 
loop. 

Terminates  the  execution  all  proeedtxpes 
and  returns  to  the  BASIC09  Command 

mode. 

Converts  numeric  data  to  string  data. 

Returns  tlie  starting  position  of  a  sequmm 
of  characters  in  a  string. 

Executes  an  OS-9  System  Call. 

Begins  a  print  operation  at  the  specified 
column. 

Calculates  the  tangent  of  a  value. 

Strips  trailing  spaces  from  the  specified 
string. 

Turn  the  trace  mode  on  and  off. 

Retxu^  the  Boolean  value  of  TRUE. 

Defines  a  new  data  type. 

See  REPEAT/UNTIL. 

See  PRINT  USING. 

Converts  a  string  to  an  integer. 

Executes  a  loop  as  long  as  a  specified  condi- 
tion is  true. 

Writes  data  in  ASCII  format  to  a  file  or 
device. 

Performs  a  logical  EXCLUSIVE  OR  on  two 
Boolean  values. 
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Commands  by  Type 


0 

DIM 

GOSUB 

OPEN 

RETURN 

BASE  1 

ELSE 

GOTO 

PARAM 

RUN 

BYE 

END 

IF/THEN 

PAUSE 

SEEK 

CHAIN 

ENDEXIT 

INPUT 

POKE 

SHELL 

CHD 

ENDIF 

KILL 

PRINT 

STOP 

CHX 

ENDLOOP 

LET 

PUT 

TROFF 

CLOSE 

ENDWHILE 

LOOP 

RAD 

TRON 

CREATE 

ERROR 

NEXT 

READ 

TYPE 

E3CmFyTHEN 

wm. 

vfwnL 

DEG 

FQR/TO/STEP 

QN/GOSUB 

REPEAT 

WHILE/DO 

DELETE 

GET 

ON/GOTO 

RESTORE 

WRITE 

Transcendental  Functions 


ACS  COS 
ASN  EXP 
ATN  LOG 

LOGIO 
PI 

SIN 
TAN 

Numeric  Functions 

ABS  LAND 

FIX  LNOT 
FLOAT  LOR 
INT  LXDR 

MOD 

RND 
SON 

SQ 

SQR 
SQRT 

String  Functions 

ASC  LEFT$ 
CHR$  LEN 
DATE$  MID$ 
INKEY 

RIGHT$ 

STR$ 

SUB 

TRIM$ 

VAL 

STR 

Miscellaneous  Functions 

ADDR  FALSE 
EOF  PEEK 
ERR  PCS 

SIZE 
TAB 
TRUE 

SYSCALL 
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Data  Types 

The  following  list  shows  the  BASIC09  data  type  you  can  specify 
when  defining  a  variable. 


Type 

Function 

Ketums  iKU£j  at  ctiXesSij 

BYTE 

Specifies  that  a  numeric  variable  is  to  store 

single-byte  values. 

INTEGER 

Specifies  that  a  numeric  variable  is  to  store 

integer  (two-%te)  wlues. 

REAL 

Specifies  that  a  numeric  variable  is  to  store 

real  (five-byte)  values. 

STRING 

Specifies  that  a  variable  is  to  store  ASCII 

characters. 

Types  of  Access  for  Files 

You  can  use 

the  following  parameters  with  the  CREATE  and 

OPEN  commands.  Check  the  individual  commands  for  informa- 

tion on  which  parameter  to  use  with  which  command. 

Parameter 

Function 

DIR 

Lets  BASIC09  access  a  directory-type  file 

for  reading.  Do  not  use  with  UPDATE  or 

wnm 

EXEC 

Lets  BASIC09  access  the  current  execution 

directory  rather  than  the  current  data 

direetiMry. 

READ 

Sets  the  file  access  mode  for  reading. 

WRITE 

Sets  the  file  access  mode  for  writing. 

UPDATE 

Sets  the  file  access  mode  for  both  reading 

and  writing. 
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Command  Mode 


The  following  chart  lists  the  commands  available  from  the 
BASIC09  Commands  mode: 


Command 


BYE  or  

I  CTRL  II  BREAK  | 

CHD 
GHX 
DIR 

EDIT  or  E 
KILL 

LIST 

LOAD 

mm 

PACK 

RENAME 

RUN 

SAVE 


Function 


Calls  the  shell  command  interpreter  to  exe- 
cute an  OS-9  command. 


Returns  you  to  the  OS-9  system  or  to  the 
program  that  called  BASIC09. 

Changes  the  current  data  directory. 

Changes  the  curreait  ^ecution  directory. 

Displays  the  name,  size,  and  variable  stor- 
age reqmrement  of  each  procedure  in  the 
workspace. 

Enters  the  procedure  editor/compilra*  mode. 

Removes  one  or  more  procedures  from  the 
workspace. 

Displays  a  formatted  listing  of  one  or  more 
procedures. 

Loads  all  procedures  from  a  file  into  the 
workspace. 

Displays  current  workspace  size  or  reserves 
a  specified  amount  of  memory  for  the 
workspace. 

Performs  a  second  compilation  and  stores 
the  resultil^  file  in  the  execution  directory. 

Changes  a  procedure's  name. 

Causes  a  procedure  to  execute. 

Writes  one  or  more  procedures  to  disk. 
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Edit  Comiiiaiids 

The  follovdng  diart  lists  the  commands  available  from  the  Edit 


mode: 

Command  Function 

I  ENTER  I  Moves  the  edit  pointer  to  the  next  line. 

+  mtm  Moves  the  effit  pointffl"  forward  a  specified 

number  of  lines. 

+  *  Moves  the  edit  pointer  past  the  last  line. 

—  num  Moves  the  edit  pointer  back  a  specified 

nmmber  of  lines. 

-  *  Moves  the  edit  pointe?  lo;  Ifee  fl»st  line. 

text  A  space  followed  by  text  inserts  an  unnum- 

bered line  before  the  current  line. 

Bim  Typing  a  line  number  with  or  without  text 

following  it  inserts  the  line  into  the 
procedure. 

Une  I  ENTER  I  Moves  &e  edit  poittter  to  the  line  Um. 

c/strt/jstrW  Changes  the  text  strl  to  the  text  str^. 

f^lstirl/strS  Changes  all  occurrences  of  strl  to  str2. 

d  Deletes  the  current  line. 

d*  Deletes  all  the  lines  in  the  procedure. 

1  Lists  the  current  line. 

1*  Lists  all  the  lines  in  the  current  procedure. 

q  Terminates  the  edit  session. 

r  Renumbers  lines  from  the  first  line  number, 

in  increments  of  10. 

r*  Renumbers  all  numbered  Tines  In  incre- 

ments of  10.  The  first  line  number  is  100. 

r  line  Renumbers  lines  from  Urn  in  increments  of 

10. 

r  line  num  Rmumbers  lines  from  line,  in  increments  of 

num. 

s/str  Searches  for  the  first  occurrences  of  str. 

8*/8tr  Searches  for  all  occurrences  of  str. 
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Dabug  Qoznziiiindi 

The  following  table  lists  all  the  Debug  commands  and  what  they 

accomplish: 


Command 


Function 


BREAK 

CONT 
DEG/RA.D 

DIR 
Q 

LIST 

PRINT  var 
STATE 

STEPnum 

TRON/TROFF 


os-i 


nils  BMIG()9  to  execute  the 
command  or  program. 

Sets  a  breakpoint  at  the  specified 
procedure. 

Causes  procedure  execution  to  continue. 

Selects  either  degrees  or  radians  as  the  unit 
of  angle  measurement  for  trigonometric 
functions. 

Displays  the  jnrocedures  in  the  workspace. 

Leaves  the  Debug  mode  for  the  System 
mode. 

Assigns  a  raew  'vriue  to  a  ra3is&. 

Displays  a  source  listing  of  the  suspended 

procedure. 

Displays  the  value  of  the  specified  variable. 

Lists  the  nesting  order  of  all  active 
p-ocedures. 

Causes  execution  of  the  suspended  proce- 
dure in  specified  increments. 

Turns  tibe  tcaee  functisa  cm  and  o&. 
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BASIC09  is  made  of  keywords  (functions  and  statements)  that 
you  use,  with  their  parameters,  to  instruct  the  computer  to  pear- 
form  certain  operations. 

This  chapter  is  a  complete  reference  for  all  of  BASICOS's 
keywords. 

Keyword  Format 

The  reference  to  each  keyword  is  organized  in  this  manner: 

•  The  keyword. 

•  The  proper  syntax  (spelling  and  form)  for  using  the 

keyword. 

•  A  brief  description  of  the  keyword's  purpose  or  effect. 

•  Descriptions  of  any  parameters  or  arguments  for  the 

•  Notes  about  sg^mi  &atees  or  reqsdi'c^jQi^ts  of  the 
wca'd,  when  appropiiiale. 

•  One  ca*  more  mmx^Sm  fiar  using  the  k^rword. 

•  One  or  more  smts^  procedures, 

This  format  can  vary  slightly,  depending  on  the  complexity  of 
each  keyword.  For  instance,  some  keywords  require  parameters 
or  arguments,  and  others  do  not.  Some  keywords  are  self- 
explanatory  and  do  not  require  a  sample  procedure. 

fkm  %iitax  line 

The  second  line  in  each  command  or  kesrword  reference  is  the 

syntax  line.  This  line  uses  keyword  constants  and  keyword  vari- 
ables to  show  you  how  to  construct  a  command  line.  Constants 
are  words,  numbers,  or  symbols  that  you  iype  e^ai^jr  as  they 
appear.  Variables  are  words  that  only  represent  the  actual 
words,  numbers,  or  symbols  that  you  must  supply  for  the 
command. 
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All  variables  are  italic.  When  yoa  see  an  italicized  word,  you 
know  that  you  must  supply  some  other  word,  name,  symbol,  or 
value  in  place  of  that  word.  If  a  word,  symbol,  or  value  is  not 
italicized,  type  it  exactly  the  way  it  appears  in  the  syntax  line. 

The  syntax  line  also  uses  symbols  to  help  you  understand  how  to 
construct  a  command  line.  These  symbols  are: 

[  ]  Words,  names,  value,  or  symbols  contained  between 
right  and  left  brackets  are  optional.  You  can  use  them 
or  not,  depending  on  what  you  want  to  accomplish  with 
the  command. 

. . .  Ellipsis  indicates  that  the  last  parameter  can  be 

repeated. 

The  following  syntax  line  for  DELETE  requires  only  one  param- 
eter, the  variable  pathname. 

DELETE  "pathname" 

Because  pathname  is  italicized,  you  know  that  you  must  replace 
it  with  other  text — in  this  case  the  pathlist  to  the  file  you  want 
to  delete.  If  you  wanted  to  delete  a  file  named  Test  fi-om  the 
ROOT  directory  of  Drive  /Dl,  this  syntax  line  tells  you  that  you 

must  type: 

delete  "/dl/test" 

Other  syntax  lines  are  more  complex,  such  as  the  line  for 
CREATE: 

CREOTE  mpath, "pathlist"   [access  model 
l+access  mode] I + . . . ] 

This  line  tells  you  how  to  create  a  path  to  a  file  or  device. 
Because  the  number  symbol  (#)  is  liot  italicized,  you  type  it 
after  the  blank  space  following  the  keyword.  However, 
path,pathlist,  and  access  mode  are  all  italicized.  You  must 
replace  them  with  other  names  or  values. 

The  access  mode  variable  is  contained  within  brackets.  This  tells 
you  that  it  is  optional.  You  can  include  an  access  mode,  or  not.  If 
you  don't,  BASIC09  opens  the  path  in  the  Update  Mode. 

The  second  access  mode  shows  that  the  command  allows  two 

access  mode  parameters,  preceded  by  a  plus  symbol.  The  ellipsis 
show  that  you  can  have  even  more  access  mode  parameters. 
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Other  syntax  lines  show  that  no  parameters  are  required,  such 
as: 

DATE$ 

This  faKuaand  returns  the  caurent  date.  Ilttr®  is  aotbifflf  it 
requires,  and  you  can  do  nothing  else  with  it. 

Sample  Programs 

The  sample  programs  in  this  chapter  are  complete.  That  is,  you 
can  type  them,  run  them,  and  get  a  result.  The  procedures  let 
you  see  the  syntax  and  form  of  a  command,  as  well  as  showing 
you  how  it  might  be  used  in  a  program. 

Because  the  programs  are  executable,  the  manual  shows  unfor- 
matted listings  (without  relative  address,  indented  control  struc- 
tures, and  so  on).  This  helps  eliminate  confusion  for  you  when 
ytm,  l^pe  "^cm  program.  Ibu  can  t^e  it  exactly  as  it  appears,  exit 
the  editor,  and  run  the  procedure. 
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ABS  Return  absolute  value 


Syntax:  ABBinmaber) 

Function:  Computes  the  absolute  value  of  number.  A  number's 
absolute  value  is  its  magnitude  without  regard  to  its  sign. 
Absolute  \^lues  are  aliK^p  positive  or  zero. 

Parameters: 

number  Any  positive  or  negative  number. 

Examples: 

PRINT  ABSf-66) 
X-ABStY) 

Sample  Program: 

The  Mlowing  procedure  asks  you  to  type  the  temperature,  and 
makes  an  appropriate  comment.  It  uses  ABS  to  ^t  the  absolute 

value  of  the  temperature. 

PROCEDURE  temperature 
DDIM  TEMPi  lNTlMR 

DIHPUT  "What's  the  temperature  outside?  (Degrees 
Fl. , .",TEMP 

□IF  TEMP<0  THEN 

□PRINT  "That's  ";  ABS(TEMP);  "  below 

zero  IDODBrrrrrrr ! " 

□END 

□ENDIF 

□IF  TEMP=0  THEN 

□PRINT  "Zero  degrees?  That's  mighty  cold!" 

□EMB' 

□ENDIF 

□PRINT  TEMP;    "  degrees  above   zero?  That's   kind  of 

balmy. . ." 

□END 
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ACS  Return  arccosine 


Syntax:  M^&{nmnher) 


Function:  Calculates  the  arccosine  of  number.  Use  the  DEG  or 
RAD  commands  to  tell  BASIC09  if  number  is  in  degrees  or 
radians.  If  you  do  not  specify  degrees  or  radians,  the  de&ult 
is  radians. 

Parameters: 

number  The  number  for  which  you  want  to  compute 

the  arccosine. 

Examples: 

PRINT  Ascc.esei ) 

Sample  Program: 

The  procedure  calculates  the  arccosine  of  a  value  you  type  and 
expresses  the  result  in  degrees. 

PROCEDURE  arccosine 
DDEG 

QDIM  NUM:REftL 

□INPUT   "Enter   a    number    between    -1    and  1",NUM 

□  PRINT    "The    arccosine    of     ";     NUM)     "     is  "; 

ACSCNUM) 
□END 
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ADDR  Retam  tibie  location  of  a  variable 


%nta3E:  ADDBCuajxie) 

Function:  Returns  the  absolute  location  in  a  process's  address 
space  of  the  variable,  arr^,  ov  data  structiire  assigned  to 
name.  The  address  returned  is  #iat  etf  the  first  i:^wxm!b&  in 
the  vaxiable.  If  the  variable  is  numeric,  one  or  more  of  the 
locations  might  contain  zero. 

For  instance,  if  you  use  ADDR  to  obtain  the  address  of  an 
integer  variable  that  contains  the  value  44,  the  first  address 
location  (byte)  contains  0,  and  the  second  location  contains  44. 

Parameters: 

name  The  name  of  a  string,  a  numeric  variable,  an 

array,  or  a  data  structure. 

Examples: 

This  procedure  disple^  the  memory  address  vfhere  a  variable 

named  X  resides: 

PRINT  ADDRCX) 
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Sample  Program: 

This  procedure  uses  ADDR  to  tell  you  the  memory  location  of 
the  variable  that  stores  your  k^board  entry. 

F>j?DCEDURE  address 

□DIM  A : INTEGER 
□DIM  TEST:STRING 

□  INPUT  "Type  a  string  of  characters ... ".TEST 
□A=ADDRCTESTJ 

□PRINT  "The  string  you  typed  is  stored  at  addresa 
";  A 

□PRINT  "This   is  what   it  contains:..." 
□FOR  T»A  Tn  A*LEH(TEST) 
□PRINT  CHR$CPEEKCT)); 

□NEXT  T 

□PRINT 
□END 
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AND  performs  a  logicid  AND  operation 


Syntioc:     wpm-mtdt  AND  opetaaM 

Function:  Performs  the  logical  AND  operation  on  two  or  more 
values,  returning  a  vjilue  of  either  TRUE  or  FALSE. 

Parameters: 

operandi         Can  be  either  numeric  or  string  values. 
operand2 

Examples: 

PRINT  A>3  AND  B>3 

PRINT  A$="YES"  AND  B*-"YES" 

Sample  Program: 

The  following  program  calculates  an  insurance  premium  rate 
that  is  based  on  the  answers  to  some  lifestyle  questions.  Every 
time  you  press  Cy)»  the  premium  rate  goes  up.  The  procedure 
xtsm  AND  to  increase  the  rat©  %  two  piarcent  if  you  both  smoke 
and  drink. 

PROCEDURE  policy 

□DIM  PDLICY_VALUE,RATE:REAL 

□DIM  SMDKE,DRINK:STRINGC1 ] 

DPDLICY_VALUE  =  1  000000. 

DRATE=.001 

□INPUT  "Do   you    smoke?    ( Y/N SMDKE 

OINPUT  "Do  you  drink?   C Y /N )...", DR I NK 

□IF  SMQKE="Y"  AND  DRINK="Y"  THEN  RATE=RATE+ . 02 

□ELSE 

DIF  SMOKE="V"  THEN  RATe=RATE+ . 01 

□ENDIF 

□IF  DRINK="Y"  THEN  RATE=RATE+ . 01 

□ENDIF 

□END IF 

□PRINT  "Your  pfeinium  is  RATE«PDL1CY_VALUE 
□END 
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ASC  Returns  ASCII  code 


Function:  Returns  the  ASCII  code  ftr  tiie  first  character  of 

string. 

ASC  returns  the  value  as  a  decimal  number.  If  string  is  null 
(contains  no  characters)  BASIC09  returns  Error  67  (Illegal 
Argument). 

Parameters: 

string  Any  string  type  wriable  or  constant. 

Examples: 

PRINT  ASCC'Hello") 
X  =  ASC(A$) 

Sample  Program: 

The  following  procedure  determines  whether  the  first  character 
you  enter  is  a  hexadecimal  digit.  To  do  this,  it  gets  the  ASCII 
mbm  of  the  charatte-  and  compares  it  to  the  ranges  &r  charac- 
ters between  X  and  0  and  A  and  P. 

PROCEDURE  hexcheck 
□DIM  A : I NTEGER 
□DIM  HEXNUM: STRING 
□LOOP 

□  INPUT  "Etiter  a  hexadecimal  va  1  ue  HEXNUM 

□A=ASCCHEXNUM)    \  (♦   GET  THE  ASCII   CODE  ») 

□EXITIF  A<48  OR  A>57  AND  A<65  OR  A>70  THEN 
□PRINT  "Not  a  hex  number." 
QEND 

DENDEXIT 
□PRINT  "Ok." 
□ENDLOOP 
□END 
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ASN  Returns  arcsiue 


^rntax:  ASNinmnbex) 

Function:  Calculates  the  arcsine  of  ram^bet.  ASN  expresses  its 
result  in  radians  unless  you  specify  o&6rwise  (see  DEG). 

Parameters: 

number  The  number  for  which  you  want  to  calculate 

the  arcsine. 

Examples: 

PRINT  flSCC.6561) 

Sam{ite  Ww^gPieam 

Hie  i}I]0>«!^i^  program  calemlates  the  arcsine  of  a  ntunber  you 
enter  and  expresses  the  result  in  degrees. 

PROCEDURE  arcsine 
□DIM  NUM:REAL 
□DEG 

□INPUT  "Enter  a  number  C-1    to  1)  ",NUM 

□PRINT    "The    arcsine    of    a    " ;    MUM;    "  la  

ASN(NUM) 

□  END 
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ATN  Returns  arctangent 


Syntax:  Kn^imimber) 


Function:  Calculates  the  arctangent  of  number. 
Parameters: 

number  The  number  for  which  you  want  to  find  the 

arctangent. 

Examples: 

PRINT  ASC( .6561 ) 

Samiile  Prograais 

This  procedure  calculates  aresine,  arccosine,  and  arctangent  fm 
a  value  you  enter. 

PROCEDURE  anglecalc 
□DIM  NUM:REftL 
flDEG 

tllNPUT  "Enter  a  TiamBef  •',NtJl«t 

□PRINT 

□  PRINT  "  ", "Aresine", "ArccoBine", "Arctangent" 
DPS  I  N'f  ««Rumher"  ,  "Degrees"  ,  "Degrees"  ,  "Degrees" 
□PRINT  "    _. _^ _ 


□IF   NUM>1    OR   NUM<-1  THEN 

□PRINT  NUM,"UNDEF","UNDEF", ATNCNUM) 

DPR  I  NT 

□END 

□ENDIF 

□PRINT  NUM,ASN(NUM),AGS(NUH3 ,ATNtNUM) 

DPR  I  NT 

DEND 
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BASE  Set  array  base 


BASE  0 
BASE  1 


Function:  Sets  a  procedure's  lowest  array  or  data  structure 
index  to  either  0  or  1.  If  you  want  to  have  the  first  elements  in 
arrays  set  to  0,  you  must  include  BASE  0  at  the  beginning  of 

the  procedure. 

The  BASE  statement  does  not  affect  string  operations  such  as 
MID$,  RIGHT$,  and  LEFT$.  BASIG09  always  ind&£BS  the 
first  character  of  a  string  as  1. 

Parameters: 

0  or  1  If  you  do  not  indicate  a  BASE  setting  in  a  pro^ 

cedure,  BASIC09  uses  a  default  of  1. 

Examples: 

BASE  0 
Sample  Program: 

This  procedure  determines  how  many  times  RND  selects  each 
number  between  0  and  11  out  of  1000  selections.  It  stores  the 
results  in  an  array  of  12  elements.  Because  it  specifies  BASE  Q, 
one  of  the  elements  in  the  array  is  0.  "rtietwar  the  pmrfare 
picks  a  random  number,  it  incitements  the  value  in  the  corre- 
sponding array  number  by  one. 

PROCEDURE  randomtest 

□BASE  B  ('  set  the  array  base  at  I. 

□DIM  RND_ARRAy(12),)(,RiINTEGER  (•  dimension  array  to  hold  results, 

□FOR  t--l  TO  11 

C]R'ND_ftRRAY(X)=«  (•  initialize  array  eleiiietti:  si  leco, 

□NEXT  X 

□SHELL  "TMDDE  -PAUSE"  C<  turn  off  screen  pause, 

□FOR  X  =  1  TO  mi 

d-SNMII)  (•  select  rtndsm  number  IBM  times. 
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□PRINT  m\-i 

□NEXT  >! 

□FOR  X=B  TO  11 

□PRINT  "RND  selected  ";  X;  "  "; 

times." 

□NEXT  X 

□SHELL  "TMDDE  PftUSE" 
□END 


(•  add  1  to  apppoppiate  elettent, 
C«  count  down  fpom  \W  to  1, 

RND_flRRflY(X);  " 
(•display  array 

(•  turn  scroll  Ipcfc  back  on, 
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BYE  End  procedure,  terminate  BASIC09 
^tax:  BYE 

Function:  Ends  execution  of  a  procedure  and  terminates 
BASIC09.  The  statement  closes  any  open  files,  but  you  lose 
ai^  ^imi@d  procedures  or  data. 

Use  WTE  to  adt  packed  pfogifams  ttat  you  call  &iiiia  and 
especially  programs  tMt  you  call  from  procedure  files. 

Parameters:  None 

Examples: 

INPUT  "Press  ENTER  to  return  to  the  system. "}Z$ 

BYE 

Sample  Program: 

This  procedure  calculates  the  payments  and  interest  of  a  loan. 
When  it  is  through,  it  exits  the  procedure  and  BASIC09  with  a 
BYE  staterqent. 
PROCEDURE  loan 

DDIM  PRIN,LENG,RATE,MDNPAYiREAL 
DDIM  RESP0NSE:STRIN6[1] 
DREPEftT 

□PRINT  "Amortization  Program" 

□INPUT  "How  much  do  you  want  to  borrow? ..." ,PR IN 

□INPUT  "For  how  many  months? ,..", LENG 

□INPUT  "fit  what  interest  rate?. . .".RATE 

nfr"8ATE/1208  . 

□B»1-1/(1+A)"LENG 

□MONPAY=PRIN»A/B 

OMDNPAY=INT(MQNPAY«100t,5)/100 

□PRINT  "Monthly  payments  are,..$"i 

□PRINT  USING  "R12.2<",M0NPflY 

□PRINT  "The  total  interest  to  pay  i5..,S"; 

□PRINT  USING  "r12.2<",NDNPftY«LENG-PRIN 

□PRINT 

□INPUT  "Do  another  calculation?, . .".RESPONSE 
□PRINT 

□PRINT 

□UNTIL  RESPDNSE<>"Y" 

□BYE 

□END 
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CHAIN  Execute  another  module 


Syntax:     CHAIN  "module  [paramei^rsK...]" 

Function:  CHAIN  performs  an  OS-9  chain  operation,  passing 
module  as  the  name  of  a  program  to  execute.  If  you  include 
other  parameters,  CHAIH  passes  to  the  ^csuMng  mod- 
ule. The  module  mugt  be  programmed  to  expect  parameters  of 
the  type  you  provide. 

CHAIN  exits  BASIC09,  unlinks  BASIC09,  and  retails  the 
freed  memory  to  08-9. 

CHAIN  can  begin  execution  of  any  module,  not  only  BASIC09 
modules.  It  executes  the  module  indirectly  through  the  shell 
in  order  to  take  advantage  of  the  shell's  parameter  processing. 
This  has  the  side  effect  of  leaving  the  initiated  shells  active. 
Programs  that  repeatedly  chain  to  each  other  eventually  fill 
memory  with  waiting  shells.  To  prevent  this,  use  the  EX 
option  to  initialize  a  shell. 

BASIC09  does  not  close  files  that  are  open  when  you  execute 
CHAIN.  HowevK-,  the  OS-9  PORK  call  passes  only  the  stan- 
dard I/O  paths  (0,  1,  and  2)  to  a  child  process.  Therefore,  if 
you  need  to  pass  an  open  path  to  another  program  segment, 
use  the  EX  shell  option. 

Parameters: 

module  The  name  of  the  procedure  module  you  want 

BASIC09  to  execute. 

parameters      String  data  passed  to  the  chained  module. 
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Examples: 

CHAIN   "ex  BASIC09  menu" 

CHAIN  "BASIC09  #10k   sort   C ""da t af i 1 e"" , 
""tempf lie"")" 

CHAIN  "DIR  /D0" 

OHAIN  "Dir;  Echo  •••  Copying  Directory  ***;  ex 
ba5ic09  copydlr" 

Sample  Program: 

This  procedure  chains  to  two  others  to  display  a  directory  or  a 
file.  It  uses  CHAIN  to  call  the  procedures. 

PROCEDURE  chaining 
□DIM  RESPDNSE:BYTE 

□PRINT  USm  "S26*","-  MENU  -"  (*  print  menu  title. 
□PRINT 

□PRINT       List  eupfent  data  dtrectery"  (•  prliit  menu. 

□PRINT  "2.  Display  a  file" 
□PRINT  "3.  Exit  to  system" 
□PRINT 

□INPUT  "Select  a  function  (1-3)  ".RESPONSE  (•  function  you  want. 
□ON  RESPONSE  GOTO  1fl»,2iB,3l«  (»  select  appropriate  function. 

100OCHA1N  "EX  BASIC89  dirlook"  (•  chain  to  list  directory. 
200DCHAIN  "EX  BASIC09  display"  (♦  chain  to  list  file. 
3a0^BYE 

PROCEDURE  dirlook 

□REM  Lists  the  specified  directory 

USHELi.  "DIR"  C»  execute  dip  epmmtnd, 

RiftTH  "EX  BiSttBi  ehalning"  (»  chaiin  liaek  is  callinf  proc. 

OEHD 

PROCEDURE  display 

□REM  Lists  the  specified  file. 

□DIM  riLE, JDB:STRING 

□INPUT  "Path  of  file  to  display. . .".FILE 

□JOB="LIST  "+FILE 

□SHELL  JOB  (•  list  speetf ie«t  file. 

□CHAIN  "EX  BftSIC09  chaining"  (•  chain  back  to  calling  proc. 

□END 
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CHD  Change  data  directory 
CHX  Change  execution  directoiy 


Syntax:     CHD  dirpath 
CHX  dirpath 

Function:  Changes  the  current  data  or  execution  directory. 

Parameters: 

dirpath  An  existing  data  or  execution  directory. 

Examples: 

CHD  •VDI /ACCDUNTS/RECEIVABLE" 

cm  "/m/mm" 

CHD  " . . " 
Sample  Program: 

This  procedure  creates  a  directory,  md  makes  it  the  data  direc- 
tory. Then,  it  taeeates  a  file  ia  t&  new  dirasetory,  €^ts  ffc©  new 
directory,  and  deletes  the  file  and  the  directory. 

PROCEDURE  chdtest 
DDIM  PATHiBYTE 

DSHELL  "MAKDIR  TEST"  <«  cfwle  m  teeetorf  nmi  TEST. 

DCHB  "TEST"  (»  mlt  TEfT  the  da:ta  tfifeetory. 

DCREHITE  #PflTH,"saiiiplefile":WRITE  {•  create  a  file  in  TEST. 

□REM        Write  data  into  the  new  file 

DWRITE  *PATK,"Thi;  file  15  for  testing  only." 

DWRITE  *PfiTH,"lt  will  be  destroyed  when  this  procedure  ends," 

□CLOSE  #PATH 

Smil  "ilST  lauplef  ile"  C»  .list  the  is»  fUe. 

□CHD  '{»  make  the  ROOT  the  data  directory. 

□SHELL  "DEL  TEST/samplef ile"'      (»  delete  the  file. 

lSHELL  "DELDIR  TEST"  (♦  delete  the  directory. 

□END 
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CHR$  Return  ASCII  character 


Syntax:  CHR$(code) 

Function:  Returns  the  ASCII  character  for  the  value  of  code. 
CHR$  is  the  inverse  of  the  ASC  function,  which  returns  the 
ASCn  code  for  a  0.vm  character.  Ebr  a  complete  listing  of 
AS€!II  codes,  see  C&ipter  @ 

Parameters: 

code  The  ASCII  value  for  a  keyboard  characta:  or 

special  bbck  graphics  character. 

Examples: 

PRINT  CHR$(88) 

Sample  Program: 

By  increasing  by  one  the  ASCII  values  of  characters  you  type, 
the  following  program  creates  a  secret  code.  It  uses  CVSE$  to  dis- 
pl£^  the  secret  code. 

PROCEDURE  secret 

DD IM  TEXT ,  SECRETL I NE :  STRIHMW] 

mm  T.CODECHARi  INTEGER 

n\W'"" 

QSECRETLiNE="" 

OPRINT  "Type  a  line  to  code  m  capital  letters,,." 
OINPUT  TEXT  («  ysu  type  a  Une, 

□FDR  T=1  TD  LEN(TEXT) 

DCDMeH«R-aSCfWIStiTE3it,T,1))  t*  loek  at  etch  ctiaracter  In  line. 
□IF  CODECHflR=90  THEN  (•  is  it  "Z"?  If  yes  then 

OC0DECHflR=G4  (•  make  it  one  less  than  "ft". 

DENDIF 

□IF  C0DECHflR=32  THEN  ('  is  character  a  space?  If  yes  then 

'QillllHAR°3t  C>  decrease  its  value  by  one. 

mmf 

C®E1!IETLIN£»SEeRETLINE«CHfi«C0DECHflRM)  («  add  1  to  characters. 
OHEXT  T 

□PRINT  SECRETLINE  (•  print  the  secret  code. 

□END 
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CHX  Change  execution  directory 
CHD  Change  data  directory 

%ntax:     CHX  tBrpath 
CHD  dirpath 

Function:  Changes  the  current  execution  or  data  directory. 

Parameters: 

dirpath  An  existing  execution  or  data  directory. 

Examples: 

CHX  "/D1/CMDS" 

CHD  "/D1 /ACCOUNTS/RECEIVABLE" 
CHD  ".  ." 
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CLOSE  Deallocate  file  or  d^ce  path 


Syntax:     GLGmM  0pmtitamm 

Function:  Deallocates  the  file  or  device  path  specified  by 

pathnum. 

When  you  OPEN  or  CREATE  a  file,  BASICQ9  allocates  a  path 
number  to  the  variable  you  supply  in  the  OPEN  or  CREATE 
command.  The  system  then  knows  the  path  by  that  number.  If 
the  path  you  CLOSE  is  to  a  non-shareable  device  (such  as  a 
printer),  the  system  releases  the  device  for  other  use.  Do  not 
close  paths  0,  1,  and  2  (the  standard  I/O  paths)  unless  you 
immediately  open  a  new  path  to  take  over  the  standard  palii 
number. 

Parameters: 

pathnum  The  name  of  variable  containing  the  path 
number  or  the  actual  number  of  the  path  to  a 
file  or  device. 

Examples: 

CLOSE  #fiLEPATH,  #PRINTERPATH,  #TERHPATH 
CLOSE  *5,  #6,  #7 

CLOSE  #1        \  {»  closes  the  standard  output  path  ♦) 
OPEN  *PATH,"/T1"       \  (♦  redirects  standard  output  ♦) 

Sample  Pro-am: 

This  procedure  creates  a  directory  named  TEST  and  changes  it 
to  the  data  directory.  It  then  creates  a  file  named  Samplefile  and 
writes  data  to  the  file.  Finally  it  changes  back  to  the  parent 
directory  and  ddetes  Samplefile  and  TEST. 
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PROCEDURE  close 
IDIM  PATHiBYTE 
ZSHELL  "MflKDIR  TEST" 
□CHD  "TEST" 

OCREflTE  #PftTHV'*5tinpltfile";WRITE  (•  create  a  new  file, 

CHRITE  #PflTH,"Thi5  file  is  for  testing  only," 

□WRITE  *PflTH,"It  will  be  destroyed  when  this  procedure  ends." 

lCLOSE  fPATH  (•  close  the  file. 

nSHELL  "LIST  samplef ile" 

QCHD 

□SHELL  "DELDIR  TEST" 

□END 
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COS  Retiun  cosine 


Syntax:  COSinumber) 

Function:  Calculates  the  cosine  of  number.  Unless  you  specify 
DEG,  COS  interprets  the  value  of  number  in  radians. 

ParameteFs: 

number  The  number  fbr  which  you  want  to  find  the 

cosine. 

Examples: 

PRINT  CDSt4S) 

Sample  Program: 

This  procedure  calculates  sine,  cosine,  and  tangent  of  a  value 
you  enter. 

PROCEDURE  ratiocBlc 
□DIM  NUMiREftL 

□DEG 

□  INPUT  "Enter  a  Tiumber  .  .  . " , NUM 
□PRINT 

DPII HT  "Number" , "S I NE" , "COS I NE" , "TAN" 

OPRINT  "■    


□PRINT  ANGLE,SIN(NUM),CDS(NUM),TANCNUM) 

□PRINT 

□END 
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CREATE   EstabUsh  a  disk  file. 


Syntax: 

CREATE  #path,"patblisf'  Laccess  mode] 
[  +  access  mode][  + ...] 


Functii^Di  €rmtes  a  file  m  a  Mak.  Wbm  you  ezmte  a  file,  jou 
can  select  one  or  more  of  the  following  access  modes  for  the 
file: 

Mode  Function 


fUSAD  Lets  you  read  (receive)  data  from  a  file  but 

does  not  let  you  write  (send)  data  to  the  file. 

WRITE  Lets  you  write  data  to  a  file  but  does  not  let 

you  read  data  from  a  file. 

UPDATE        Lets  you  both  read  from  and  write  to  a  file. 


Parameters: 

path  The  name     the  variable  in  which  BAMC09 

stores  the  numb^  of  ihe  opened  path. 

pathlist  The  route  to  the  file  or  device  to  be  opened, 

including  the  filename,  if  appropriate. 

access  mode  The  type  of  access  to  be  allowed  for  the  file  or 
device.  Use  plus  symbols  to  allow  more  than 
one  type  of  access  with  a  single  file. 


Notes: 

•  "Kju  c^  aOBeSs  fites  either  sequentially  or  randomly.  With 
rat^m  access,  you  must  establish  the  filing  system  you 
want  for  a  particular  applidUtim. 

•  Files  are  byte-addressed,  and  you  are  not  rastridted  by 
explicit  record  lengths.  You  can  read  the  data  one  l^rte  at  a 
time,  or  in  whatever  size  portions  you  want. 
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•  A  new  file  has  a  size  of  zero.  OS-9  then  escpands  the  file 
automatically  when  PRINT,  WRITE,  or  PUT  statements 
write  beyond  the  current  end-of-file. 

Examples: 

CREATE  #TRANS, "transportation": UPDATE 
CREATE  #SPDDL,  "/user 4/report": WRITE 
CREATE  #DUTPATH,nanie$:UPDATE  +  EXEC 

Sample  Program: 

This  procedure  CREATES  a  directory  named  TEST  and  makes  it 
the  data  directory.  It  creates  a  file  in  TEST  named  Samplefile, 
writes  data  to  the  file,  then  resets  the  parent  directory  as  the 
data  directory.  Finally,  it  deletes  Samplefile  and  TEST. 

PROCEDURE  close 
□DIM  PATH  I  BYTE 
QSHELL  "mm  TEST" 
DCHD  "TEST" 

DCREATE  *PATH,"5amplefile";WRlTE  ('  create  a  file. 
DWRITE  #PATH,"Thi5  file  is  for  testing  purposes  only," 
OWRITE  #PftTH,"It  will  be  destroyed  when  this  procedure  ends." 
DCLDSE  *PflTH  (♦  close  the  file. 
OSHELL  "LIST  samplefile" 
□CHD  ".," 

□SHELL  "DELDIR  TEST" 
□END 
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DATA  Store  numeric  and  string  information 


iyntax:     DATA  "it&i^V'item",...} 

Function:  Stores  numeric  and  string  constants  to  be  accessed 
by  a  READ  statement.  A  DATA  line  can  contain  up  to  254 
ehMftitws.  Each  tteaa  in  the  list  aawt  he  §«para:t«€  hy 
commas. 

You  can  place  DATA  statements  anywhere  in  a  procedure  that 
is  convenient.  BASIC09  reads  sequentially,  starting  with  the 
first  item  in  the  first  DATA  statement,  and  ending  with  the 
last  item  in  the  last  DATA  statement. 

The  following  rules  apply  to  data  items: 

•  Yon  must  place  all  string  data  between  quotation  marks. 

•  To  include  quotes  in  string-type  data,  use  consecutive 
quotation  mairfel*  Wm  this:  DATA  "He  said,  ""go 

home""  to  me'*. 

•  You  can  use  RESTORE  to  reset  the  data  pointer.  Using 
RESTORE  without  an  argument  resets  the  pointer  to  the 
beginning  of  the  data  items.  Using  RESTORE  with  a 
line  number,  resets  the  pointer  to  the  first  item  in  the 
specified  line. 

•  The  READ  statement  can  support  a  list  of  otte  or  mate 
variable  names  of  various  types.  The  data  types  in  DATA 
statements  must  match  the  variable  types  used  in  the 
corresponding  READ  statements. 

•  You  can  include  aitthn^tic  expressions  in  data  items. 
READ  causes  the  expressions  to  be  evaluated  and 
returns  the  result  of  the  expression  as  the  data  item. 

Parameters: 

item  Numeric  or  string  characters.  Enclose  string 

characters  in  quotation  marks. 
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Examples: 

DATA  1.1,1  .5,9999,"CAT","DDG" 
DATA  S I N  f  TEMP / IS ) ,  COS (TEMP • P 1 3 
DATA  TRUE , FALSE , TRUE , TRUE , FALSE 

DATA  "The  rain  in  Spain", "falls  mainly  on  the 

plain" 

Sample  Program: 

This  procedure  calculates  the  day  of  the  week  for  a  date  you 
enter.  A  data  ^fe^aooetit  contEiins  the  names  of  the  weekdays. 

PROCEDURE  weekday 

□DIM  X , DAY .MONTH,  YEAR, CALC: INTEGER 

ODIM  ANUM,BNUM,CNUM,DNUM,ENUM,FNUM,GNUM,HNUM, INUM: 

INTEGER 

□DIM  WEEKDAYC7):STRINGr9] 

□PRINT  USING  "560"", "Day  of  the  Neek  Program" 
□PRINT  USING  "SG0»","For  any  year  after  1752" 
□PRINT 

□INPUT  "Enter  day  of  the  month  as  two  digits,  such 
as  08. . .",DAY 

□INPUT  "Enter  month  B9  two  digits,   such  as 
12. . .".MONTH 

□INPUT  "Enter  year  as  four  digits,  such  as 
1988. . .".YEAR 

Df='OR  )f=1  TO  7 
OREAD  WEEKHAYCX) 
□NEXT  X 

OftNUW*! HTC . S4 1 /MONTH ) 

□BNUM-YEAR-ANUM 

0CNUM=MDNTH+12«ANUM 

□DNUM=BNUM/1 00 

□ENUM=INTCDNUM/4) 

DrNUM»INTCDNUM> 

□GNUM= I NTC5*BHUM/4) 

□HNUM=INTC13»CCNUM  +  1  )/5) 

□  I  NUM  =  HNUM  +  GNUM-FNUM  +  ENUM  +  DAY-1 

□INUM=INUM-7« INTCINUM/7)+1 

□PRINT 

□PRINT  "The  day  of  the  week  on  " ;  DAY;  "/";  MONTH; 
□PRINT  "/";   YEAR;  "  is...";  WEEKDAYC I NUM) 
□DATA  "Sunday" , "Monday" , "Tuesday" , "Wednesday" , 
"Thursday" 

□DATA  "Friday", "Saturday" 

□END  
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DATE$  Provide  dale  and  time 


Syntax:  DATE$ 

Function:  Returns  the  date  and  time.  The  OS-9  internal  date 
is  kept  in  the  format: 

year/ month/ day  hour.minutes-.seconds 

If  your  OS-9  Startup  file  contains  the  SETIME  command,  the 
system  asks  you  to  enter  the  date  and  time  whenever  it  boots. 
If  it  does  not  contain  the  SETIME  conamand,  the  date  and 

time  start  from  86/09/01:00:00:00. 

You  can  use  the  normal  string  functions  to  access  the  data 
contained  in  DATEf,  hut  ym  cannot  use  itinctions  or  opera- 
tions that  attempt  to;  dsange  or  append  to  its  values.  To  reset 
the  date  or  time  or  both,  use  the  SHELL  command,  such  as: 

SHELL  "SETIME" 

Parameters:  None 
Examples: 

PRINT  DATE$ 

Sample  Program: 

This  program  is  essentially  the  same  as  the  sample  program  for 
the  DATA  statement,  except  that  it  gets  the  day,  month,  and 
year  from  DATE$. 

PROCEDURE  date 

□DIM  X, DAY, MONTH, YEAR, CALC; INTEGER 

Zm  fiNUfl,BNUM,CNUM,DNUM,ENUM,FNUM,6NUM,HNl)M,INUM: INTEGER 

□DIM  HEEKDAY(7);STRING19) 

DnOHTH«VAL(MIDI(DATC«,4,2))  (•  get  month  frot  MTf*. 
[]DflY'VAL(MID${DflTE$,7,2))  (•  get  day  from  MTI*. 
OYEflR»VflL{"19"»LEFTICMTES,2))  (•  get  year  frein  MTEI. 

OrOR  M  TO  7 
DREAD  MEEKDAY(I(} 
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□NEXT  X 

DflNUM=lNT(,6M /MONTH) 
DBNUM^VEAR-flKUM 

DCNUM=M0NTH+12»flNUM 

DDNUM=BNUM/1BB 

□ENUM=lNT(DNUM/4) 

□FNUM=INT(DNUM) 

06NUM'lNT{5»BNUM/« 

□HNUM=INT(13«(CNUMtl)/5) 

0INUM=HNUM*GNUI1-FNUM*ENU«tDflY-l 

DlNUM=INUM-7«INTtINUM/7)+1 

□PRINT 

mm  "Totfay  is  «;  WEEKDAYfiHtlM) 

ODftTfl  "Sunday" ."Monday" , "Tuesday" , "Wednesday" , "Thursday" , "Fr iday" 
□DATA  "Saturdfly" 

□END 
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BEG  Betuni  trigonometric  caleulaticais  in 
degrees 


Syntax:  DEG 


Function:  Causes  a  procedure  to  calculate  trigonometric  val- 
ues in  degrees.  If  you  do  not  include  the  DEG  statement,  pro- 
cedures produce  radian  values. 

Parameters:  None 

Examples: 

DEG 

Samptef  Program: 

This  procedure  calculates  the  si&e,  cosim,  and  tangent  £jr  a 
value  you  enter.  Because  it  uses  the  DEG  statenmt,  it  displays 

the  results  in  degrees. 

PROCEDURE  degcalc 
□DIM  NUM:REAL 
ODEG 

□INPUT  "Entef  a  number NUM 

rPRINT 

□PRINT  "Numbe r", "SINE", "COSINE", "TAN" 

DPR  I  NT  "   


□PRINT  NUM.SINCNUM) ,CDS(NUM) .TANCMUMI 

□PRINT 
□END 


11.29 


BAEMJQ9  M^brmm 


DELETE  Erase  a  disk  file 


Syntax:     DELETE  "pathname" 


Funeiion:  DELITI  removes  a  file  from  disk  storage  and 
releases  the  portion  of  the  disk  on  which  it  resides.  When  3RJU 
DELETE  a  file,  it  is  permanently  lost. 

Parameters: 

pathname  The  complete  pathlist  to  the  file  you  want  to 
delete,  including  the  drive  and  one  or  more 
directories,  if  appropriate.  You  must  surround 
the  pathlist  with  quotation  marks. 

Examples: 

DELETE  "myfile" 

DELETE  'VD1 /ACCOUNTS/receivables" 
Sample  Program: 

This  procedure  creates  a  file  named  Samplefile,  writes  data  to 
the  file,  then  closes  it.  It  then  lists  the  file  before  deleting  it. 

PROCEDURE  close 
□DIM  PftTHiBVTE 

DCREflTE  iPfiTH,"saniplefile";WRITE  (•  create  a  file. 

□WRITE  iPflTH,"This  file  is  for  testing  purposes  only," 

□NRITE  #PATH,"!t  will  be  destroyed  when  this  procedure  ends." 

□CLOSE  *PflTH  (•  close  the  file. 

□SHELL  "LIST  samplefile" 

DDELfll  "saniplefile" 

DEND 
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DIM  Assign  variable  storage 


Syntax:     DIM  vaiiahM,'-.\h1^e!iivairiaMe\[^^^^^ 

Function:  Assigns  storage  space  and  declares  types  for  vari- 
ables, arrays,  or  complex  data  structures. 

Parameters: 


•  You  declare  simple  arrays  with  DIM  by  using  the  variable 
name,  without  a  subscript.  If  you  do  not  explicitly  declare 
variables,  the  system  makes  them  type  real  unless  they  are 
followed  by  a  dollar  sign  ($).  The  system  dimensions  vari- 
ables ending  with  a  dollar  sign  ($)  as  strings,  with  a  length 
of  32  bytes.  You  must  declare  types  of  all  other  simple  vari- 
ables as  to  type. 

•  You  can  declare  several  variables  of  the  same  type  by  sepa- 
rating them  with  commas.  To  separate  variables  of  differ- 
ent types,  follow  each  type  group  with  a  colon,  the  tjrpe 
name,  and  then  a  semicolon. 

•  Define  a  maximum  length  for  a  string  variable  by  enclosing 
the  length  in  brackets  following  the  type,  like  this: 

DIM  name: 5tring[25] 


variable 


type 


Notes: 
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If  you  do  not  define  a  maximum  length,  BASIC09  uses  a 
default  length  of  32  characters.  You  can  declare  a  shorter 
length  or  a  longer  length,  up  to  the  capacity  of  BASIC09's 
memory.  If  you  try  to  extend  a  string  beyond  its  declared 
Jm^ht  m  ^<QKid  the  default  leng^,  t&e  iy^te  ^ores  all 
6Ktra  clmracters.  Thus  the.  following: 

DIM  name : 5 t r i ng [ 1 0 ] 
name  =   " Abbe r na t h i n s ky " 

produces  the  string: 

Abbernathi 

•  Arrays  can  have  one,  two,  or  three  dimensions.  The  DIM 
format  for  dimensioned  arrays  is  the  same  as  for  simple 
variables,  except  that  you  must  follow  each  array  name 
with  a  subscript,  enclosed  in  parentheses,  to  indicate  its 
size.  The  maximum  array  size  is  32767. 

Arrays  can  be  either  of  the  standard  BASIC09  type  or  of  a 
user-defined  type.  For  information  on  creating  your  own 
types  for  simple  variables,  arrays,  and  complex  data  struc- 
tures, see  TYPE. 

Examples: 

DIM  logical sBOOLEAN 

DIM  a,b,0! INTEGER 

DIM  name, address ,zip:STRING 

DIM  name:STRING[251;  addres s : STR I NG [ 30 1 ; 

zip: INTEGER 

DIM  nol ,no2,no3:REAL;no4,no5,no6: INTEGER; 
no7:BYTE 
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Sample  Program: 

This  procedure  randomly  selects  letters  and  vowels  to  create  six- 
letter  words  that  might  look  like  alien  names.  It  first  DIMs  nine 
string  variables  to  contain  the  letters  selected  for  each  name.  It 
DIMs  two  integer  variables  to  provide  a  loop  counter  and  to  store 
the  number  of  names  ym  request. 

When  a^ed,  type  the  number  of  names  you  want  to  have  the 
procedure  gea^ate. 

PROCEDURE  alien 

□DIM  B, BEGIN, F,FINISH:STRING 

ODIM  VOWELS ,VDWEL1 ,VDWEL2:STRING 

DDIM  MIDI ,MID2:STRING 

□DIM  T, RESPONSE: INTEGER 

□VDWELS-"aeiouy" 

□INPUT  "How  many  alien  names  do  you  want  to 

see?  .  .  .".RESPONSE 

DBEGI N="ABCDFGHJKLMNPRSTVWXZ" 

□Fl NI SH="ehlmnprstvwyz" 

□FOR  T=1   TO  RESPONSE 

DB=MID*(BEGIN,RNDCie)+t ,1) 

□F=MID$(FIN1SH,RND(12)+I,1j 

□MIDI =CHR$CRND(25)+97) 

□MID2=CHR$<RNDC25)+97) 

QVOWELI •MID$CV0WELS,RNDCB)+1 ,1 ) 

□VGWEL2=MID$CV0WELS,RND(5)+1 ,1 ) 

□PRINT  B;  VDWEL1 ;  MIDI;  MID2;  VDWEL2;  F, 

□NEXT  T 

□PRINT 
□END 
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DO  Execute  procedure  lines  in  a  loop 


proclines 
ENDWHILE 

Function:  Establishes  a  loop  that  executes  the  procedure  lines 
between  BO  and  ENDWHILE  as  long  as  the  result  of  the 
expression  following  WHILE  is  true.  Because  the  loop  is 
tested  at  the  tap,  the  lines  within  the  loop  are  never  executed 
unless  expression  is  true. 

Parameters: 

expression       A  Boolean  expression  (produces  a  result  of 
True  or  Ealse). 

prodines         Are  program  lines  to  execute  if  the  expression 
is  true. 

See  WHILE/DO/ENDWHILE  for  more  information. 
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ELSE  Execute  alternate  aeMim 


Syntax:     IF  condition  THEN 


action 
ELSE 


secondary  action 
ENDIF 


Function:  ELSE  provides  access  to  a  secondary  action  within 
an  IF/THEN  test.  When  the  condition  tested  by  IF  is  not 
true,  BASIC09  executes  the  secondary  action  preceded  by 
ELSE. 

P^ameters: 

condition         A  Boolean  expression  (produces  a  result  of 


True  or  False). 


action 


A  line  number  to  which  the  procedure  is  to 
transfer  execution,  or  a  program  statement.  If 

action  is  a  line  number,  do  not  include  the 
ENDIF  statement  in  the  IF  test. 


secondary 
action 


One  or  more  program  statements. 


Bbr  more  infijrmation,  see  IF/THEN/ELSE 
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END  Terminate  a  p'ocedure 


Syntax:     END  ["texf] 

Function:  Mads  procedure  execution  and  returns  to  the  calling 
procedtixe,  or  to  the  highest  level  procedure.  If  you  provide 
output  text  far  END,  it  functions  in  the  same  manner  as 
PRINT.  You  can  use  END  several  times  in  the  same  proce- 
dure. END  is  not  required  as  the  last  statement  in  a 
procedure. 

Parameters: 

text  A  literal  string  or  a  string-type  variable. 

Examples: 

END  "Program  Terminated" 

LAST$="Ses5ion  over" 
END  LAST$ 

Sample  Program: 

This  procedure  calculates  a  loan's  term,  using  END  to  termi- 
nate routines. 

PROCEDURE  leaner 

DBIM  YOUPA Y , PR  I NC I PLE , I NTEREST , NUMP AY , YEARS , 
MONTIS  5 RiftU 

ODIM  RESPaNtlriTRINSiCI  I 

□REPEAT 
□PRINT 

□PRINT  USING  "S45*","Loaii  Terms" 

□PRINT 

□INPUT  "       Amount  of  Regular  Payment s ...", YDUPAY 
□  INPUT  "       Enter   the  Pr i nc i p  1  e .  .  . " , PR  I  NCI PLE 
□INPUT  "       Enter  the  Annual   Interest  Rate...", 
I NTEREST 

□INPUT  "       Enter  the  Number  of  Payments 
Yearly. . .".NUMPAY 
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DYEARS  =  -(LQG(1 -  PR  I NC I P LE • CI NTEREST/ 1 00)/ 
(NUMPAY* YDUPAY))/(LDG( 1 + I NTEREST/ 1 00/NUMPAY)* 
NUMPAY)) 

□MaNTH=INTCyEARS«1  2+.S) 
aYEflRS= INTtMDNTH/1  2) 

DMDNTH=MDNTH-YEARS*1 2 

□PRINT  "       The  Term  of  Your  Loan  is  ";   YEARS;  " 

years  and        MONTH;  «  ntontha." 

□INPUT  "Calculate  another  or  Quit  <C/Q3?...", 

RESPONSE 

OUNTIL   RESPGNSE<>"C"  AND  RESPDNSE<>"c" 
□END  "Goodbye...!   hope   I   helped  you." 
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ENDEXIT  Leave  loop  if  a  conditiom  is  True 

Syntax:     EXITIF  condition  THEN 
proclines 
ENDEXIT 

Function:  ENDEXIT  terminates  an  EXITIF  test.  You  always 
use  EXITIF/THEN/ENDEXIT  inside  a  procedure  loop.  If  the 
Boolean  expression  tested  by  EXITIF  is  true,  BASIC09  ate- 
cutes  the  program  statements  between  THEN  anct  ENDTEXIT 
and  then  transfers  program  operation  outside  the  loop.  If  the 
condition  tested  by  EXITIF  is  not  true,  loop  execution  contin- 
ues at  the  statement  following  ENDEXIT. 

Parameters: 

condition  A  comparison  operation  that  returns  either 
True  or  False,  such  as  A  =  B,  A<B,  or 
A  =  B  =  C. 

pF&clines  One  or  more  statements  to  perform  if  the  Boo- 
lean expression  tested  by  EXITIF  is  True. 

For  more  information,  see  EXITIF/THEN/ENDEXIT 
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ENDIF  Close  IF  slat^eat 


Syntax:     IF  condition  THEN 
action 
[ELSE 

secondary  action] 
ENDIF 


Function:  ENDIF  terminates  an  IF/THEN  condition  test.  If 
the  condition  tested  by  IF  is  true,  BASIC09  executes  the 
statements  between  THEN  and  ENDIF.  If  the  condition  tested 
by  IF  is  ncf  trtie,  BASIC09  transfers  execution  to  the  proce- 
dure line  Mlowing  ENDIF  w  C@pMonaIly^  e^eeute^  &e  state- 
ments following  ELSE. 


Parameters: 

eondUkm        A  Boolean  ^p^eislon  Ciirddiaies  a  result  of 
True  or  Bklse). 

action  A  line  number  to  which  the  procedure  is  to 

transfer  execution.  Action  can  also  be  a  pro- 
gram statement.  If  action  is  a  line  number,  do 
not  include  the  ENDIF  statement  in  the  IF 
test. 

seemdary        A  pofograin  ft^tw^ot. 
action 

Jbr  more  information,  see  IF/THEN/ELSE/ENDIF. 
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ENDLOOP  Close  LOOP  statement 


Syntax:  LOOP 

statemenKs) 
ENDLOOP 

Function:  ENDLOOP  terminates  a  procedure  loop  established 
by  the  LOOP  command.  BASIC09  endlessly  executes  all  proce- 
dure statements  between  LOOP  and  ENDLOOP  repeatedly 
tthless  a  coniliBn  test  wi^iin  the  locp  ^txdh  m  IIHES^ 
THEN/ENDEXIT,  or  IF/THEN)  transfers  execution  outside  of 
the  loop. 

Para]petii>s: 

statements)      One  or  more  procedure  lines  that  execute 

within  the  loop. 

For  more  information,  see  LOOP/ENDLOOP. 
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ENDWHILE  Close  WHILE  statement 


^ntax:     WHILE  condition  DO 

proclines 
ENDWHILE 


Fuliction:  Rjrms  the  bottom  of  a  WHILE  loop.  WIffLE  causes 
the  procedure  lines  between  DO  and  ENDWHILE  to  execute 
as  long  as  the  result  of  the  expression  following  WHILE  is 
true.  BeciKOie  the  loop  is  tested  at  the  top,  the  lines  within 
the  loop  are  never  executed  unless  the  expression  is  true. 

Parameters: 

eondition         A  Boolean  expression  (produces  results  of  True 
or  False). 

proclines         Are  program  lines  to  execute  if  the  expression 
is  true. 

Pbr  more  information,  see  WHILE/DO/ENDWHILE. 
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EOF  Test  for  end-of-file 


Syntax:  EOBX^aM 


Function:  Tests  for  the  end  of  a  disk  file.  The  fUnction  returns 
a  value  of  True  when  it  encounters  an  end-of-file;  otherwise,  it 
retxims  Ealse.  Use  EOF  with  a  READ  or  GET  statement. 

Parameters: 

path  The  number  of  the  path  you  are  accessing. 

BASIOO0  automatically  stores  a  path  aumaber 
into  the  variable  you  specify  during  a 
CREATE  or  OPEN  operation. 

Examples: 

IF  EOF(#PATH)  THEN 
CLDSE  #PATH 
ENDIF 

Sample  Program: 

This  procedure  redirects  a  listing  of  the  current  directory  into  a 
file  named  Dirfile.  It  then  lists  Dirfile  to  the  screen.  EOF  tells 
the  WHILE/ENDWHILE  loop  when  the  READ  operation  reaches 

PROCEDURE  readfile 

□DIM  A:STRING[80] 

□DIM  PATH:BYTE 

□SHELL  "DIR   >  dirfile" 

□OPEN  #PATH,"dirf ile":READ 

□MHrLE  NOT  EOF(#PATH>  DO 

□READ  #PATH,ft 

□PRINT  A 

□ENDWHILE 

□CLOSE  -fPATH 

OEHfi 
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ERR  Return  error  code 


Syntax:  ERR 

Function:  Returns  the  error  code  of  the  most  recent  error. 
BASIC09  automatically  sets  the  ERR  code  to  zero  after  you 
reference  it.  ERR  is  only  useful  when  used  in  conjunction  with 
BASIC09's  ON  ERROR  error  trapping  functions. 

See  Appendix  A  for  a  list  of  all  BASIG09  error  codes. 
Parameters:  None 
Examples: 

ERRNUM  =  ERR 

IF  ERRNUM  =  218  THEN 

PRINT  "File  already  exists.   Please  use  anether 
f  i 1 ename . " 
END  IF 

Sample  Program: 

This  procedure  displays  the  contents  of  a  file  you  select.  If  the 
file  doesn't  exist  (Error  216,  Pathname  not  found),  the  procedaie 
uses  ERR  to  tell  you.  If  an  error  other  than  Error  216  occurs, 
the  p'acedure  displays  I  can't  handle  error  XX,  where  xx  is 
the  code  of  the  error. 
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PROCEDURE  readfile 

□DIM  READFILEiSTRING;  fl:STRlNS[8e] ;  PflTHiBYTE 

1BDINPUT  "Type  the  pathlist  of  the  file  to  read, READFILE 

DON  ERROR  GOTO  \U   (•  if  an  error  occurs,  skip  to  line  \M. 

DOPEN  iPftTH.REWDFILljIiW 

□NHILE  EOF(#PATH)<>TRUE  DO 

□READ  *PATH,A 

□PRINT  A 

DENDWHILE 

OEIOSI  'PATH 

DEND 

HIOERRNUM=ERR  (•  store  the  error  code  in  ERRNOM, 
DIP  ERiiliMglf  THIN  ¥«  If  We  teesn'l  tatlst  sa^  so. 
□PRINT  "I  can't  find  the  file... Please  try  again." 
□ON  ERROR 

□GOTO  IB 
□ENDIF 

EiPtHiT  "lafFf,  1  can't  handle  error  nuiber  "•,  ERRNUM  (»  other  error. 

□CLOSE  #PflTH 

□END 
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ERROR  Simulate  an  etror 


Syntax:     IKEOB  eocfe 

Functioii:  Simulates  the  error  specified  by  code.  You  would 
zoainly  use  this  command  to  test  ON  ERROR  GOTO  routines, 
Wbm  BASIC09  encounters  an  ERROR  statement,  it  proceeds 
as  if  the  error  corresponding  to  the  specified  code  has 
occurred.  Refer  to  Appendix  A  for  a  listing  of  error  codes  and 
their  meanings. 

Parameters: 

code  The  code  of  the  error  you  want  to  simulate. 


Examples: 

ERROR  207 

ERRNUM  =  ERR 

IF  ERRNUM  =   207  THEN 

PRINT  "Memory  is  full. 

saved  to  disk," 

EKDIF 


The  current  data  is  being 


Sample  Program: 

This  program  creates  a  file  named  Testl.  Before  creating  the 
file,  it  checks  to  see  if  it  already  exists.  If  the  file  exists,  the  pro- 
cedure deletes  it.  An  error  trap  catches  any  error  that  might 
occur.  To  test  if  the  trap  works  for  Error  216,  "Pathname  not 
found",  the  statement  ERROR  216  is  inserted  as  the  fourth  line. 
After  testing  the  trap  to  make  sure  it  works,  delete  this  line  to 
use  the  procedure. 
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PROCEDURE  errortest 

□DIM  PATH,ERRNUM:BYTE;    RE SPDNSE : STR I NG [ 1 ] 
□BASE  0 

DON  ERRQR  GOTO  10        (♦  set  error  trap 

QCRROR  216  C*  aiinulBte  error 

□DELETE  "test1" 

DGOTQ  100 

1 BDERRNUM'ERR 

OIF  £RRNIJM=216  THEN 

DINPUT  "File  doesn't  exist. .  .contitiue? 

(Y/N)", RESPONSE 

□IF  RESPONSE="N"  THEN 

DEND  "Procedure  terminated  at  your  request..." 

QENDIF 

DENDIF 

OON  ERROR  {*   turn  off  error  trap. 

100DCREATE  #PATH,"te5t1 ":WRITE 

□END 
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EXITIF/THEN/ENDEXIT 

Exit  from  loop  if  a  condition  is  true 


Syntax:     EXITIF  condition  THEN 
statement 
ENDEXIT 


Function:  Use  these  statements  with  loop  constructions  (par- 
ticularly LOOP  and  ENDLOOP)  to  provide  an  exit  for  what  is 
othenvise  an  endless  loop.  EXITIF  performs  a  test  of  a  Boo- 
lean expression,  such  as  A<B.  The  THEN  statement  precedes 
any  operation  you  want  to  execute  if  the  expression  is  true. 
You  must  always  follow  EXITIF  with  an  ENDEXIT. 

If  the  Boolean  expression  following  an  EXITIF  is  false,  execu- 
tion of  the  program  transfers  to  the  statement  immediately 
following  the  body  of  the  loop  (after  the  ENDEXIT  statement). 
Otherwise,  BASIC09  executes  the  statement(s)  between 
EXITIF  and  ENDEXIT,  then  transfers  control  to  the  state- 
ment following  the  body  of  the  loop. 

You  can  also  use  EXITIF  and  ENDEXIT  with  types  of  loop 
constructions  other  than  LOOP/ENDLOOP. 

I^ameters: 

Boolean  A  comparison  operation  that  returns  either 

expression        True  or  False,  such  as  A  =  B,  A<B,  or 
A  =  B  =  C. 

statement         An  operation  to  be  performed  if  the  Boolean 
expression  tested  by  EXITIF  is  True,  such  as: 
PRINT  A  is  less  than  B. 
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Examples: 

LOOP 

COUNT=eaONT*1 

EXITIF  CDUNT>100  THEN 

DONE   =  TRUE 

ENDEX IT 

PRINT  QDUNT 

x  =  eoawr/g 

ENDLDQP 


Sample  ProgrMMs 

This  procedure  simulates  a  gambling  machine  by  randomly 
selecting  among  several  fruit  names  and  displaying  them.  It 
gives  you  a  starting  stake  of  $25  and,  depending  on  the  combi- 
nation of  fruit  selected,  it  adds  or  subtracts  from  your  stake. 

If  your  stake  drops  to  zero,  an  EXITIF  statement  ends  the  proce- 
dure and  tells  you  that  you're  broke. 

PRDCEDUgE  oneaftfi 

CDIM  FRUTT1 .FRUrif ,Ff U IT3 , STAKE : I NTEGER ;  FRUITCSJ: 

STRINGCG] 
□STAKE=25 

DPRINT     \  PRINT  "You  have  $";  STAKE;  "  to  play 
with." 

□FDR  T=1    TO  8 

oread  fruit(t) 
□next' T 

DLd'OP 

□FRUIT1 =RNDC7)+1    \ FRU I T2= RNDC 7 ) + 1    \ FRU I T3= RNDC 7 ) + 1 

□  PRINT  FRUITCFRUITI  );   "  ";   FRU I T( FRU I T2 ) ;    "  "; 
FRUIT(FRUIT3) 

niF  FRUITCFRUITI )=FRUITCFRUIT2J  AND  FRU I TC FRU I T1 ) = 
FRUITCFRUIT3J  THEN  STAKE=STAKE+ 1 0 

□ELSE 

□IF  FRUITCFRUITI )=FRUIT(FRUIT2)   OR  FRU I TC FRU I T1 ) = 
FRUITCFRUIT3)  OR 

□FRUITCFRUIT2)=FRUITCFRUIT3)  THEN 
□STAKE=STAKE+1 

□  ELSE 

□STAKE=STAKE-1 

□ENDIF 

□ENDIF 
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OREM  exit  play  loop  is  stake  is  less  than  $1  . 
OEXITIF  STAKE* 1  THEN 

□  PR  I  NT 

□PRINT  "You're  Bu s t ed . . . Be t t e r  go  home." 

Di:N»f;iiT 

DPRINT  "Youp  stake  is  now  $";   STAKE;     . " 
□PRINT 

□PRINT 

□INPUT  "Press   ENTER   to  pull  again... ",Z$ 
□ENDLOOP 

□END 

□DATA  "ORANGE" ."APPLE" ."CHERRY", "LEMDN" , "BAN AN A 
□DATA  "PEAR" , "PLUM" , "PEACH" 
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EXP  Return  natural  exponent 


Syntax:  EXP(aainber) 


Function:  Returns  the  natural  exponent  of  number,  that  is,  e 
(2.71828183)  to  the  power  of  number.  Number  must  be 
positive. 

This  function  is  the  inverse  of  the  LOG  function.  Therefiire, 
number  =  EXP(L0G(num6er)). 

Parameters: 

number  A  positive  value. 

Examples: 

PRINT  EXP(2) 

Sample  Program: 

This  procedure  calctilates  the  exponent  of  values  in  the  range 
0-1. 

PROCEDURE  exprint 

□FDR  T=0  TO   1    STEP  .03 

□PRINT  EXP{T),EXPCT+.01),EXPCT+.02) 

□NEXT  T 

OEND 
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FALSE  Assign  Boolean  value 


Syntax:     variable = FALSE 

FuBcticm:  MLSE  is  a  Bodteaa  ftxtu^ittt  tet  alwsps  reiums 
False.  You  can  use  FALSE  and  TRUE  to  assign  values  to  Boo- 
lean variables. 

Parameters:  None 

Examples: 

DIM  TESTsBOQLEAN 
TEST-FALSE 

Sample  Program: 

The  procedure  uses  a  Boolean  variable  to  store  True  or  Blaise, 
depending  on  whether  you  answa:  some  questions  correctly  or 

incorrectly. 

PROCEDURE  quiz 

□DIM  REPLY, VALUEiBODLEANj  ANSWER s STR I NG[ 1 ] ; 

QUESTIDN:STRING[80] 

□FDR  T-1   TO  5 

□READ  QUESTION, VALUE 

□PRINT  QUESTION 

□PRINT  "(T)   =  TRUEDD^DaDQCF)  =  FALSE" 

□PRINT  "Select  T  or  FiDD"; 

□GET  #1 .ANSWER 

□IF  ANSWER="T"  THEN 

□REPLY=TRUE 

□ELSE 

□REPLY=FALSE 
□END IF 

□IF  REPLY=VALUE  THEN 

□PRINT     \   PRINT  "That's  Co r r ec t .  .  . Good  Show!" 
□ELSE 

□PRINT  "Sorry,  you're  wrong ...  Bet ter  Luck  next 
time." 

□ENDIF 

□PRINT     \   PRINT     \  PRINT 
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□NEXT  T 

□DATA  "In   computer   talk,   CPU  stands   for  Central 
Packaging  Unit.",  FALSE 

□DATA  "The  actual  value  of  G4K  is  65536 
bytes  ."',T1?UE 

□DATA  "The  bits   in  a  byte  are  normally  numbered  0 

through   7?", TRUE 

□DATA   "BASIC09  has   four   data   t ype s .", FALSE 
□DATA  "The  LAND  function  is  a  Boolean  type 
operator  •••.FALtE 
□END 
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FIX 


Syntax:     FIX(  vaiue) 


Function:  Rounds  a  real  number  to  the  nearest  whole  numbK" 
and  converts  it  to  an  integer-type  niimber.  Fix  perfoiros  a 
function  that  is  the  opposite  of  the  FLOAT  function. 

Parameters: 

value  Any  real  number. 

Examples: 

PRINT  FIXCA) 

Sample  Pro-am: 

This  procedure  displsQrs  the  PIXed  values  of  seven  constants. 

PROCEDURE  ppiTitfix 
□PRINT  FIXd  .2) 
□PRINT  FIXCI .3) 

□  PRINT  FIXd  .5) 
□PRINT  FIXCI .8) 
□PRINT  Fixe 99. 566666) 

□  PRINT  FI  X(50 . 1  ) 

□  PRINT  FI  X( . 7654321  ) 
□PRINT  FIX(-12.44) 
□PRINT  FIX(-9.99) 
□END 
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FLOAT  Convert  from  integer  or  l^te  to  real 


Syntax:  FLOAT(va7ue) 


Function:  Converts  an  integer-  or  byte-type  value  to  real  type. 
FLOAT  performs  a  function  that  is  the  opposite  of  the  FIX 
function. 

Parameters: 

vabie  An  integer-  or  byte-type  number. 

Examples: 

DIM  TEST: INTEGER 
TEST-44 

PRINT  FLQATCTESTJ/S 

Sample  Program: 

This  procedure  uses  FLOAT  to  produce  a  real  number  result  of 
an  inch  to  centimeter  conversion. 

PROCEDURE  coTivert 

□DIM  T: INTEGER;  MEASURE : STR I NGC 11] 
DFQR  T=1   TO  10 
Dir  T-1  THEN 
□MEASURE-"centimeter  " 

□ELSE 

OMEASURE  =  "ceiitimeters" 

□ENDIF 

□PRINT  Ti  "  ";  MEASURE;  "  is        FLDATCT) • . 3937 ; 
"  inches." 

□NEXT  T 
□END 
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FOR/NEXT/STEP  Establish  a  loop 


FOR  variable  =  init  val  TO  end  val  [STEP  value] 
[procedure  statements] 
NEXT  variable 


Function:  Establishes  a  procedure  loop  that  lets  BASIC09  exe- 
cute one  or  more  procedure  statemeute  a  specified  number  of 
times.  The  variables  ym  use  can  be  either  integer  tir  tmL  type 

and  can  be  negative,  positive,  or  both.  Loops  using  integer 
values  execute  faster  than  loops  using  real  values. 

BASIC09  executes  the  lines  following  the  FOR  statement  until 
it  encounters  a  NEXT  statement.  Then  it  either  increases  or 
decreases  the  initial  value  by  one  (the  default)  or  by  the  value 
given  STEP. 


Parameters: 

variable 

init  val 

end  val 

value 

procedure 
statements 


Any  legal  numeric  variable  name. 

Any  numeric  constant  or  variable. 

Any  numeric  constant  or  variable. 

Any  numeric  constant  or  variable. 

Procedure  lines  you  want  to  be  executed 
'vdithin  the  loop. 


Notes: 


If  you  provide  an  initial  value  that  is  greater  than  the  final 
value,  BAS1C09  skips  the  pcograsoi  loop  artirely  unless  you 

specify  a  negative  STEP  value.  Specifying  a  negative  value 
for  STEP  causes  the  loop  to  decrement  from  the  initial 
value  to  the  end  value. 
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•  When  execution  reaches  the  NEXT  statement  in  a  positiv© 
stepping  loop,  and  the  step  value  is  less  than  or  equal  to 
the  end  value,  BASIC09  branches  back  to  the  line  after 
FOR  and  repeats  the  process.  When  the  step  value  is 
greater  than  the  end  value,  BASIC09  transfers  ^eeutidn  to 
the  statement  following  the  NEXT  statement. 

•  When  execution  reaches  the  NEXT  statement  in  a  negative 
stepping  loop,  and  the  step  value  is  greater  than  or  equal 
to  the  end  value,  BASIC09  branches  back  to  the  line  after 
FOR  and  repeats  the  process.  When  the  step  value  is  less 
than  the  end  value,  execution  continues  fttHlwi^  tig  SP^T 
statement. 

Examples: 

FDR  CDUNTEI?  =  1   to  100  STEP  .5 
PRINT  COUNTER 
NEXT  COUNTER 

FDR  X  =  10  TO  1  ITEP  -1 

PRINT  X 
NEXT  X 

FDR  TEST  =   A  TD  B  STEP  RATE 
PRINT  TEST 
NEXT  TEST 

Sample  Program: 

This  procedure  uses  two  nested  FOR/NEXT  loops  to  proda^  a 
multiplication  table. 

PROCEDURE  multable 

DPRINT  USING  "S45'"', "MULTIPLICATION  TABLE" 
□PRINT 

DDIM  I,J:INTEGER 

DFDR  1=1  TO  9 

DFDR  J=1    TD  9 

□IF   J>1  THEN 

□PRINT   I»J;  TABC5*J); 

□ELSE  PRINT   I»J;    "|  "; 

mnnir- 

□NEXT  J 

□IF    1=1  THEN 

□PRINT  "" 
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□PRINT 

 ■•  . 

T 

□  ENDI  F 
□PRINT 
□NEXT  I 
□END 
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GET  Read  a  direct-access  file  record 


Syntax:     GET  ^patb,vamame 

Function:  Reads  a  fixed-size  binary  data  record  fi-om  a  file  or 
device.  Use  GET  to  retrieve  data  fi"om  random  access  files. 

Although  you  usually  use  GET  with  files,  you  can  also  use  it 
to  reeeive  data  for  any  outputtittg  de^ee,  such  as  a  keyboard 
or  another  computer.  By  dimensioning  a  string  variable  to  the 
length  of  input  you  want,  you  can  use  GET  to  read  a  specified 
number  of  keystrokes,  then  continue  program  etecution  with- 
out requiring  |  enter  |  to  be  pressed. 

For  information,  about  storing  data  in  random  access  files,  see 
Chapter  8,  **Disfe  Files/*  Also  see  PUT,  SEEK,  and  SIZE. 

Parameters: 

path  A  variable  name  you  choose  in  which  BASIC09 

sttam  fhe  number  of  the  path  it  opens  to  the 
device  you  specify  or  one  of  the  standard  I/O 

paths  (0,  1,  or  2). 

varname  The  variable  in  which  you  want  to  store  the 

data  read  by  the  GET  statement. 

Examples: 

GET  #PATH,DATA$ 
GET  #1  .RESPONSE* 
GET  #INPUT, INDEXCX) 

Sample  Program: 

This  procedure  directs  a  directory  listing  to  a  file  named  Dirfile. 
GET  then  reads  the  file,  one  character  at  a  time  in  order  to 
determine  which  characters  are  valid  filename  characters.  The 
procedure  creates  a  file  containing  all  the  filenames  in  the 
directory. 


11-58 


BA&C0$  Crnismmd  Refsrmce  1 11 


PROCEDURE  filenames 

□DIM  DIRECTORY, FILENflME:STRlNG;  CHflRflCTER:STRING[l ] ;  FILES(125)!STRIN0I1Sli 

P»TH,CDUNT,T:IKTE6ER 

DCOUNT'I 

□FILENAME'"" 

□FOR  T=1  TO  125  C«  initialize  array  elements  to  null. 

□FILES(T)="" 

□NEXT  T 

□INPUT  "Pathlist  of  directory  to  read... ".DIRECTORY  (•  dir  to  copy. 

□ON  ERROR  GOTO  10 

□DELETE  "dirfile"  (•  If  dlrfile  already  exists,  delete  it. 
le^DN  ERROR 

□SHELL  "DIR  "♦DIRECTORY*"  >  dirfile"  («  copy  directory  into  file. 
□OPEN  #PflTH,"dirfile"iREAD  («  open  the  file  for  reading. 

□REPEAT 

□REM  Get  characters  from  the  file  until  the  first  carriage  return  ■  the 

beginning  of  the  first  filename. 

□SET  #F«tH,C«M€TER  (•  get  characters  from  the  file. 

□UNTIL  CHflRflCTER'CHRni3) 

□REM 

2BDLD0P 

□EXITIF  EDF(#PATH)  THEN 

□GOTO  201  (•  quit  when  end  of  file, 

□ENDEXIT 

□REM  get  a  character  from  the  file  until  it  finds  a  non-valid  filename 
ehsractert 

QGET  #PflTH,CHftRftCTER 
□REM 

□EXITIF  CHARflCTER<»"  "  OR  CHARACTER)"!"  THEN 

□GOTO  m 

□ENDEKTT 

□FILENAME=FILENAME*CHARACTER  (*  build  the  filename. 

□ENDLOOP 

IBOHILE  NOT(EOF(*PATH))  DO 

□GET  iPATH, CHARACTER  (•-checl:  for  non-valid  filename  characters. 
OEXlTlf  CHARACTER)''  "  AND  CHARACTER<'"z"  THEN  (•  check  if  valid  char. 

□COUNT=COUNTM 

□F1LES(C0UNT)=FILENAME  (•  store  filename  in  array. 
□PRINT  FILENAME,  (•  display  the  extracted  filename. 
□FILENAME'""  (•  set  variable  to  NULL, 

OnLENA«E'FILENflME*CHARACTER  (t  last  character  begins  new  filename. 
□GOTO  28  C»  go  get  the  rest  of  filename. 

□ENDEXIT 
□ENDWHILE 
28(!^CL0SE  *PATH 
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□DELETE  "dirfile"  (»  names  are  all  in  array  so  delete  file. 
□CREATE  #PfiTH,"dirfile":WRITE  (•  create  the  file  again. 
□FOR  T=1  TO  COUNT 

DtlRITt  #PIITH,FILES{T)  (»  fill  thft  file  with  individual  filenames. 
nNEXT  T 
□CLOSE  #PflTH 
□PRINT 

□PflHT  "□□□□□□□•The  directory  has  "i  CDUNTi  "  entries'." 
□PRINTa"a]QI]ni]They  are  irow  stored  In  a  file  named  Dlrflle." 

□END 
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GOSUB/RETURN 

Jump  to  subroutine/  Return  from  subroutine 


Syntax:     GOSUB  lin&mmber 

Function:  Branches  program  execution  to  the  specified  line 

number. 

BASIC09  lets  you  write  programs  with  line  numbers  or  with- 
out. You  can  also  mix  numbered  and  un-numbered  lines 
within  a  single  procedure.  This  means  that,  to  use  GOSUB, 
you  need  to  number  only  the  first  line  of  the  subroutine  to 
which  you  want  to  branch. 

Every  subroutine  you  access  with  GOSUB  must  contain  a 
RETURN  statement.  You  can  call  a  subroutine  in  this  man- 
ner as  many  times  as  you  want.  When  BASIC09  encounters 
the  RETURN,  it  transfers  program  ^ecution  to  the  line  fol- 
lowing the  GOSUB  statement. 

"55)u  can  precede  GOSUB  with  a  test  statement,  such  as  IF  or 
WHEN,  that  makes  branching  conditional. 

You  can  nest  GOSUB  statements  to  any  depth,  depending  on 
your  computer's  free  memory. 

Parameters: 

linermmher      The  number  of  the  line  where  procedure  esce- 
cution  is  to  continue. 

Examples: 

GOSUB  100 
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Sample  Program: 

The  following  procedure  asks  you  for  two  numbers  and  an  opera- 
tor. It  determines  the  line  to  jump  to  by  the  position  of  the  oper- 
atiif  X&  a  table.  GOSUB  sends  the  procedure  to  execute  the 
proper  routine.  RETURN  sends  the  execution  back  to  the  main 
routine.  To  quit,  enter  a  negative  value. 

PROCEDURE  calc 

□DIM  NUM1 ,NUM2:REAL;   DP : STR I NG [ 1 ] ;  ArlHTEOER 
1DINPUT  "NUMBER   1  "jNUMI 

□IF  NUMi  «a  jnm 

□END 
□ENDIF 

□INPUT  "NUMBER  2  ";NUM2 
□INPUT  "DPERATOR  ";0P 
□fi=SUBSTRC DP, "+-*/*") 
□□N  f\  GDSUB  1  0  ,20  ,30  ,40  ,50 

□GOTO  1 

10^PRINT  NUM1+NUM2  \  RETURN 
20DPRINT  NUM1-NUM2  \  RETURN 
SBOPiTNT  NUM1»NUf12  \  RfTURN 
40DPRINT  NUM1/NUM2  \  RETURN 
S0nPRINT  NUM1  NUM2  \  RETURN 
□END 
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IF/THEN/ELSE/ENDIF 

Test  a  Boolean  expression 


Syntax:     IF  condition  THEN  Unemimh&r 
[ELSE 

secon^uy  action 
ENDIF] 

IF  condition  THEN 

action 

CELSE 

secondary  action] 
ENDIF 


Function:  Tests  a  Boolean  expression  and  executes  action  if  the 
expression  is  true.  Optionally,  the  statements  execute  a  sec- 
ondary action  if  the  expression  is  not  true.  Each  IF  statement 
must  be  accompanied  by  THEN.  If  action  is  a  line  number, 
you  can  omit  the  ENDIF  statement.  For  instance,  both  of  the 
following  statements  operate  in  the  same  manner: 

IF  T=5  THEN  1 0 

IF  T=5  THEN 
GOTO  10 
ENDIF 


Parameters: 

condition 
linermmber 

action 


secondary 
action 


A  Boolean  expression  (produces  True  or  I^lse). 

A  line  to  which  the  procedure  is  to  transfer 

execution  if  condition  is  true. 

One  or  more  procedure  statements  to  be  exe- 
cuted if  condition  is  true. 

One  or  more  procedure  statements  to  execute 
if  condition  is  false. 
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Examples: 

IF  A>B  THEN   1 00 

IF  A<B  THEN  100 
ELSE 

A  =  A-1 
ENDIF 

IF  TEST=TRUE  THEN 

PRINT  "The  test   is  a  success..." 

ENDIF 

IF  A  <  B  THEN 

PRINT  "ft   is   less  than  0" 

ELSE 

PRINT  "B  is    less   than  A" 
ENDIF 

Sample  Program: 

The  following  procedure  is  a  purge  procedure.  Use  it  only  with 
the  GET  Sample  Prog^Piffla  to  fiekte  one  or  more  files  from  your 
current  diuecstery-. 

The  Filenames  procedure  (see  GET)  stores  the  current  directo- 
ry's filenames  in  Dirfile.  This  procedure  reads  Dirfile,  displays 
all  the  filenames,  then  asks  you  for  a  wildcard.  Type  in  charac- 
ters that  identify  a  group  of  files  you  want  to  delete.  The  pro- 
gram deletes  all  files  that  contain,  in  the  same  order  and  case, 
thie  characters  you  type. 

For  instance,  if  you  have  four  files  named  Test,  Filel,  File2,  and 
FileS,  and  you  type  a  wildcard  of  "File,"  the  procedure  deletes 
Filel,  File2,  and  File3,  but  does  not  delete  Test.  Delete  all  of  the 
files  in  a  directory  by  typing       as  the  wildcard. 

Use  this  program  carefully.  Be  sure  you  are  in  the  right 
dlpeetwy  and  that  the  wildcat  ^haTacters  ym  type  m&  not  con- 
tained in  filenames  other  than  the  ones  you  want  to  delete.  You 
might  want  to  add  a  prompt  to  the  procedure  that  lets  you  con- 
firm each  deletion  before  it  happens. 
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PROCEDUIE  purge 
DDIM  PATH: INTEGER 

□DIM  NAMEC 1 00) : STR ING 
ODIM  WILDCARD:STRING 

ox-« 

□OPEN  #PATH,"dirf ile":READ 
□NHILE   NDTCEOFC-fPATH))  DO 
□X=X+1 

□READ  #PATH,NAME<X) 
□ENDWHILE 

□FDR  T=1    TO  X 
□PRINT  NANECT), 
□NEXT  T 

□INPUT  "Wildcard  Charac t er s . . . " , W I LDCARD 
□FOR  T=1   TO  X 

□ON   ERROR  GOTO   1 00 

DIP   SUBSTRCWILDCARD,NAME(T))>0   OR  WILDCARD="»" 
THEN 

□PRINT  "DELETING  ";  NAMECT);  "   " 

□DELETE  NAMECT) 

JENDI F 
10DNEXT  T 
□END 

100npRlNT        ♦  ♦  ERROR  •  •  «        NAMECT);  "  eaTinot 
be  de 1 e t ed . . c on t i nu i ng . " 
□GQTa  10 
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INKEY  Read  a  keypress 


Syntax:     RUN  INKEY(5trm£) 

Function:  Reads  a  keypress,  and  stores  tiie  character  of  the 
key  in  the  specified  string  variable. 

Parameters: 

string  is  a  string  variable  into  which  INKEY  stores 

the  character  you  press. 

Examples: 

DIM  CHAR:STRING[1 ] 
CHAR="" 

WHILE  CHAR=""  DO 

RUN  INKEYtCHAR) 

EHDWHILE 

PRIKT  ASC<CHAR> 
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Sample  Pro-am: 

PROCEDURE  Calculate 
□DIM  CHAR:STRING[1 ] 
□DIM  LDDKUP:STRING[7] 
□DIM  FIRST, SECaND:REAL 

□dim  flag: integer 
:lddkup  =  "  +  -*/''<>" 
1  flag=0  \char="" 

DPRINT  "Enter  the  first  number  to  evaluate..."; 

□INPUT  FIRST 
DIF  FIRST=0  THEN 
□GDTQ  100 
□ENDIF 

□PRINT  "Enter  the  second  number  to  evaluate..."; 

□INPUT  SECOND 

□PRINT  "Press  the  key  of  the  operator  you  want  to 
use.  .  .  " 

□PRINT  "  *   -  #  /  "  <  >   . . ."; 
DWHILE  CHAR=""  DD 
□RUN  INKEYCCHAR) 

□ENDWHILE 
□PRINT 

□FLAG  =  S,UBSTR(CHAR  ,  LOOKUP) 

□ON  FLAG  GOTO  10,20,30,40,50,60,70 

10   PRINT  FIRST+SECOND   \  GOTO  1 

20   PRINT  FIRST-SECOND  \  GOTO  1 

30  PRINT  FIRST*SECQND  \  GOTO  t 

40  PRINT  FIRST/SECOND  \  GOTO  1 

50  PRINT  FIRST"SECOND  \  GOTO  1 

G0   PRINT  FIRST<SECDND   \  GOTO  1 

70   PRINT  FIRST>SECOND  \  GOTO  1 

Iff  PRINT  ''Procedure  Terminated  Due  to  0 

Input  ..." 

□  END 
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INPUT  Get  data  from  a  device  path 


Syntax:     INPUT  [#path,]  [prompt,]  variable  [,variable...l 

Function:  INPUT  accepts  input  from  the  specified  |>atli.  (Bie 
default  is  the  keyboard.)  When  a  procedure  encounters 
INPUT,  it  displays  a  question  mark  and  awaits  data  from  the 
specified  path.  If  you  provide  a  string  type  prompt  for  INPUT, 
it  displays  the  text  of  the  prompt,  rather  than  a  question 
mark. 

INPUT  stares  the  data  it  collects  in  the  variable  you  specify. 
The  type  of  the  receiving  variable  must  match  the  type  of 

data  received. 

Because  INPUT  sends  data  (the  question  mark  prompt  or  the 
user-specified  string  prompt),  it  is  really  both  an  input  and  an 
output  statement.  This  means  that,  if  you  use  a  path  other 
than  the  standard  input  path,  you  should  not  use  the 
UPDATE  mode.  If  you  do,  the  prompts  produced  by  INPUT 
write  to  the  file  specified  by  the  path  number. 

If  the  data  received  does  not  match  the  type  of  data  INPUT 
expects,  it  displays  the  message: 

«# INPUT  ERROR  -  RETYPE** 

followed  by  a  new  prompt.  "You  must  then  enter  the  entire 
input  line,  of  the  correct  type,  to  satisfy  INPUT.  Pbr  more 
information,  see  C^T. 
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Parameters: 


path 


Either  a  variable  containing  the  path  number, 
or  the  absolute  path  number  to  the  file  or 
device  from  which  you  want  to  receive  input.  If 
you  want  to  receive  input  from  the  keyboard, 
do  not  include  a  path  number. 


prompt 


Text  you  type  as  a  message  to  be  displayed 
when  BASIC09  executes  an  INPUT  statement. 


mriabh 


The  variable  name  in  which  you  want  to  store 
the  data  received  by  INPUT.  The  type  of  vari- 
able must  match  the  type  of  input. 


Examples: 

INPUT  NUMBER, NAMES, LOCATION 
INPUT  #PATH , X , Y ,Z 

INPUT  "What    is  your   selection:  ";CHDICE 
INPUT  #HDST,"What '5  your    ID  number?  ",IDNUM 

Sample  Progrgtm? 

This  procedure  calculates  the  day  of  the  week  for  a  specified 
date.  It  asks  you  for  the  date  using  the  INPUT  command. 

PROCEDURE  weekday 

□DIM   X ,Y,D,M,CALC:  INTEGER;   D A Y , MONTH : STR I  HOC  2 ] ; 
YE,A,R:STRING[4:  ;,  WEEKDAY   C 7 )  :  STR  I  NG  [ 9 ] 
DD m    N DM ,  BN UM ,  CNUM ,  BNUM ,  mm ,  FN UM ,  6N UM ,  HNUM , 
INUM: INTEGER 

□PRINT  USING  "S80   ","Day  of   the  Week   P r og r am" , "Fo r 

any  year  after  1752" 

DPRINT 

□PRINT  "Enter   day  Ce.g.    083:    " ;      \    INPUT  DAY 
□PRINT   "      Enter   month    Ce.g.    12):    ";      \    INPUT  MONTH 
□PRINT  "     Enter  year    (e.g.    1986):    ";      \    INPUT  YEAR 
□Y  =  VALC¥iai,S  \M=VAL(MONTH)  \D=VALCDftY> 
□FOR  X=1   TO  7 
□READ  WEEKDAYCX) 
□NEXT  X 

nANUM=INTC .6+1 /M) 
nBNUM=Y-ANUM 
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□CNUM=M+1 2*ANUM 

DDNUM=BNUM/1 00 

DENUM= I NTCDNUM/4> 

QFNUM=INTCDNUM) 

DSHOM"  I  FlTtS»BNUl»I/  4  > 

DHNUM=INTC1 3»CCNUM+1)/5) 

0INUM=HNUM+GNUM-FNUM+ENUM+D-1 

□INUM=INUM-7*INTCINUM/7)+1 

□PRINT 

□PRINT  "The  day  of  the  week  on  " ;  M;   "/";  D; 

"/";    Y;    '•   i5...";   WEEKDAY  (INUM) 

□DATA  "Sunday" , "Monday" , "Tuesday" , "Wednesday" , 

"Thur  s  day" , "F  r 1  day" ."Saturday" 

□END 
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INT  Convert  real  number  to  whole  number 


Syntax:     INT(  vaiue) 


Function:  Converts  a  real  number  to  a  whole  number  by  trun- 
cating any  fractional  part  of  the  real  number. 

Parameters: 

mlm  Any  n^ative  or  positive  real  number. 

Examples: 

PRINT  INT(77.89) 
PRINT  INTCNUM) 
PRINT  INTC-8.12) 

Sample  Program: 

The  RND  function  produces  real  numbers.  This  procedure  uses 
INT  to  convert  the  real  RND  output  to  integer  values. 

PROCEDURE  integer 
□DIM  T: INTEGER 
OFDR  1=1   TO  10 
[JR=RNDC50)-l2i 
□PRINT  R , INT<R) 
□NEXT  T 
OEND 
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KILL  Remove  a  procedure  from  mem^y 


Syntax:     BIIoL  promd!mF& 

Function:  Unlinks  (removes)  an  external  procedure  from  the 
BASIC09  procedure  directory.  If  the  procedure  is  not  external, 
but  tmSm  im  BMEOOS's  workspace,  KILL  has  m  ^ct. 

Use  KILL  to  remove  auto-loaded  (packed)  procedures  that  are 

called  by  RUN  or  CHAIN.  You  can  also  use  KILL  with  auto- 
loading procedures  as  a  method  to  overlay  programs  within 
BASIC09. 

Warning:  Be  certain  you  do  not  KILL  an  active  proce- 
dure. Also  be  certain  that  when  you  use  RUN  and  KILL 
together,  that  both  statemeaits  use  the  same  string  vari- 
able that  contains  the  name  of  the  procedure  to  RUN 
and  KILL. 

Parameters: 

procedure  The  name  of  the  external  procedure  you  want 
to  KILL.  Procedure  can  either  be  a  name  or  a 
variable  eontaining  the  procediire  name. 

Examples: 

PRDCEDURENAME$   =  "AVERAGE" 
mn  PRDCEDWRENAMES 
KILL  PRQCECURENAME* 

INPUT  "Whtch  test  do  ypu  want  to  run?  ",TEST$ 
RUN  TEST* 
KILL  TEST? 
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Sample  Program: 

This  procedure  calls  a  procedure  named  Show  to  display  ASCII 
values  on  the  screen.  When  it  no  longer  needs  tihie  Show  proce- 
dure, it  removes  Show  from  memory  using  KILL. 

PROCEDURE  produce 
DDIM  T,U:  INTEGER 

OBIM  HUM, NUM1 , NUM2 .TABLE , PRDCNAME : STR I NG 

□PRDCNAME=SHDW 
DTABLE="1 23456783ABCDEF" 
DFDR  T=8  TQ  15 
□FOR  U=1  TO  15 
0NUM1-MID$(TftBLE,T,1) 
DNUM2=MID$(TABLE,U,1) 

□NUM  =  liUM1+NUM2      (•  parameter  to  pass  to  Show. 
ORUN  PROCNAME(NUM) 
DNEXT  U 
DNEfT  T 

□KILL  "PRQCHAME"  (•  remove  Show  from  the  worlcspace, 

□END 

PROCEDURE  SHOW 
□PARAM  HUM: STRING 
□SHELL  "DISPLAY  "+NUM 
□END 
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LAND  Returns  the  logical  AND  of  two  numbers 


Syntax:  LANB^mmmt^m^^ 


Function:  Performs  the  logical  AND  ftinction  on  a  byte-  or 
integer-type  value.  The  operation  invdves  a  bit-by-bit  logical 
AND  of  the  two  numbers  you  specify.  Ibr  instance*  if  you 
LAND  5  and  6,  the  logic  is  like  this: 

Decimal  5  =  Binary  0101 
Decimal  6  =  Binary  0110 

0101 
AND  0110 

0100  =  4  Decimal 

Bai^anetsps: 

miml  A  hyte-  or  integer-type  number. 

num2  A  hyte-  or  integer-type  number. 

Examples: 

PRINT  LANDCI 1,12) 
PRINT  LANDC$20,$FF) 

Sample  Program: 

The  following  procedure  asks  eight  questions  and  uses  the  eight 
bits  of  one  byte  (contained  in  the  variable  STORAGE)  to  indicate 
either  a  '*yes"  or  **tio'*  answer.  If  the  answer  is  *^s,"  it  sets  a 
corresponding  bit  to  1.  If  the  answer  is  "no,"  it  sets  a  corre- 
sponding bit  to  0,  using  LAND.  This  procedure  operates  in  con- 
junction with  the  sample  program  for  LXOR. 
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PROCEDURE  questions 

□DIM  QUEST1DN:STRING[6B);  T: INTEGER;  K, STORAGE; BYTE 

DD!M  ANSWER: SIR  INGE  1i 

OXM 

□FDR  T=T  TD  8 

□READ  QUESTION 

□PRINT  QUESTION;  "  (Y/N)?  "; 

□GET  #8, ANSWER 

□PRINT 

□IF  ANSWER="y"  OR  ANSWER'T  THfN 
□STORAGE=LDR(STDRAGE,X)  (•  OR  STORAGE  if  yes, 
□ELSE 

aSTOBAGMAND(STDRAGE,,LNDT(D)  (•  LAND  STORAGE  with  NOT  value  if  no. 

□END  IF 

□X=X«2 

□NEXT  T 

□RUN  5uiiimary(ST0RflGE) 
□END 

□DATA  "Do  you  have  more  than  one  Color  Computer" 

□DATA  "Do  you  use  your  Color  Computer  for  games" 

□DATA  "Do  ystl  use  your  Color  Computer  for  word  processing" 

□DATA  "Do  you  use  your  Color  Computer  for  business  applications" 

ODATA  "Do  you  use  your  Color  Computer  at  home"' 

□DATA  "Do  you  use  your  Color  Computer  at  the  office" 

□DATA  "Do  you  use  your  Color  Computer  more  than  two  hours  a  day" 

□DATA  "Do  you  share  your  Color  Computer  with  others" 
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LEFT  mmmm  characters  from  the  left  portion 
of  a  string 


Syntax:  lMFT$islTh^,lmigtb) 

Function:  Returns  the  specified  number  of  characters  from  the 
specified  string,  beginning  at  the  leftmost  character.  If  length 
is  the  same  as  or  greater  than  the  number  of  characters  in 
string,  then  LEFT$  returns  all  the  characters  in  the  string. 

Parameters: 

string  A  sequence  of  ASCII  characters  or  a  string 

variable  name. 

length  The  number  of  characters  you  want  to  access. 

Examples: 

PRINT  LEFT$("HQTDaG",3) 
PRINT  LEFT$CA«,6) 

Sample  Prograon! 

The  fi>terltti  p'oced^e  exacts  the  first  name  feam  a  liit  of  ten: 
names  with  the  LEFT$  ftinction. 

PROCEDURE  firstname 

DDIM  NAMES: STRING;  F1RSTNAME;STR1N0[1B] 
CPRIHT  "Here  are  the  first  names t" 
DFOR  M  TO  H 
mm  NAMES 

[]PDINTER=SUB5TR("  ".NAMES)  (♦  find  space  between  first  and  last  names. 
OFIRSTHflME=LEFT$(NAMES,P0lNTER-1)  (•  extract  first  name. 
□PRINT  FIRSTNAME  (•  print  first  name. 
DNIIT  T 

□rND 

DDATfl  "Joe  Blon5ki","Mil;e  Marvel", "Hal  Skeeini5h","Fred  Laungly" 

□DATA  "Jane  Mistey", "Wendy  Paston", "Martha  Upshong", "Jacqueline  Rivers" 

DDflTA  "Susy  Reetmore", "Wilson  Creding" 


11-76 


BASIC09  Command  Reference  1 11 


LEN  Returns  the  length  of  a  string 


Syntax:  LEN(siring) 

Function:  Returns        number  of  characters  in  a  string. 
Counts  blanks  or  spaces  as  characters. 

Parameters: 

string  A  literal  string  or  a  vaa^iable  containing  string 

characters. 

Examples: 

PRINT  LENC"ABCDEFGHIJKLM"J 
PRINT  LEN{NAME$3 
NAME$  =  "JDE" 

ADDRESS$  =  "2244  LANCASTER" 
TOTALLEN  =  LEN(NAME$)+LEN(ADDRESS$) 

Sample  Program: 

The  following  procedure  uses  LEN  to  determine  which  naBMB  in  a 
liftfc  longest. 

PfDCEDURE  lorgname 

IDIM  NAMES, LNAMEiSTRING;  LONGEST, LENGTHi INTEGER 

□NflMES=""  \LNAME=""  \LENGTH=8  \LDNGEST=8 

OFTO  T'f  TO  ie 

OtEfiB  NAMES 

DLENGTHHENfUAMES) 

□  IF  LDNGE5KLENGTH  THEN 

□LDNGEST=LENGTH 

mmmm 

□ENDIF 
DfCKT  T 

OPIINT  "The  longest  name  is  "\  LNAME;  "  with  ";  LONSEST;  "  characters." 
□END 

DDATA  "Joe  llon3ki«r«mt!»  Kami",*!  SI:ee«|sii«,'"FT:«{l  Vsw^ 
ODATA  "Jane  Misty", "Wendy  Paston", "Martha  Ups.hon|","Jtcqueiln8  Rivers" 
□DATA  "Susy  Reetmore", "Wilson  Creding" 
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LET 


a  variable's  value 


Syntax:     [LET]  variable  =  expression 


Function:  Assigns  a  value  to  a  variable.  BASIC09  does  not 
require  the  LET  statement  to  assign  values  but  does  accept  it 
in  order  to  be  compatible  with  versions  of  BASIC  that  do 
require  it. 

ijpteife  The  variable  to  which  you  want  to  assign  a 


•  The  result  of  the  LET  expression  must  be  of  the  same  type 
as,  or  compatible  with,  the  variable  in  which  it  is  stored. 

•  BASIC09's  assignment  function  accepts  either  =  or  :=  as 
assignment  operators.  The  :=  form  helps  to  distinguish 
assignment  operations  from  comparisons  (test  for  equality) 
and  is  compatible  with  Pascal  programming. 

•  Use  BAStGOS's  assignment  function  to  copy  entire  arrays  or 
complex  data  structures  to  another  array  or  complex  data 
structure.  The  data  structures  do  not  need  to  be  of  the 
same  type  or  shape,  but  the  size  of  the  destination  struc- 
ture must  be  the  same  as  or  larger  than  the  source  struc- 
ture. This  means  the  assignment  function  can  perform 
unusual  type  conversions.  For  example,  you  can  copy  a 
string  variable  of  80  characters  into  a  one-dimensional 
array  of  80  bytes. 


value. 


expression 


Either  a  numeric  or  string  constant  or  a 
numeric  or  string  expression. 


Notes: 
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Examples: 

LET  A   =  5 
LET  A    : =  B 
ANSWER   =   A   ♦  B 
LET  NAME$    :=  "JDE" 

NAME   $   =   FIRSTNAME$   +   ■■■■  +  LASTNAME$ 

Sample  Pro-am: 

This  procedure  uses  LET  to  assign  a  random  value  to  the  vari- 
able R. 

PROCEDURE  getint 
DDIM  T: INTEGER 
□FDR  T=1    TD  10 
□LET  R=RND(50)-25 
□PRINT  R,INTCR3 
□NEXT  T 
DEND 
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LNOT  Performs  a  logical  NOT  on  a  number 


^fntax:  LNOTCvalne) 

Function:  Performs  the  logical  NOT  function  on  an  integer  or 
byte  type  number.  The  operation  involves  a  bit-by-bit  logical 
complement  operation  of  the  number  you  specify.  Ear  instance, 
if  value  is  188,  the  logic  looks  like  this: 

188  Decimal  =  10111100  Binary 

NOT  10111100 
=  01000011 

01000011  Binary  =  67  Decimal 

LNOT  changes  each  bit  in  a  binary  number  to  its  complemen- 
tary binary  value — all  1  values  become  0  and  all  0  values 
become  1.  LNOT  returns  an  integer  result;  it  is  not  a  Boolean 
operator. 

Parameters: 

value  Any  decimal  or  hexadecimal  integer  or  byte 

number.  Precede  hexadecimal  numbers  with  $. 

Examples: 

PRINT  LNDT<88) 
A   =  LNDT(B) 
A   =  LN0TC$44) 

Sample  Pro|^am: 

This  procedure  uses  one  byte  (contained  in  the  variable  STOR- 
AGE) to  indicate  the  results  of  eight  questions.  Each  bit  in  the 
byte  indicates  a  Yes  or  No  answer  (Yes  =  1  and  No  =  0).  The  com- 
bination logic  of  LAND  and  LNOT  masks  the  byte  X  so  that  it 
affects  only  the  appropriate  bit  of  STORAGE  to  set  it  to  0  if  the 
answer  is  No.  LOR  sets  the  appropriate  bit  to  1  if  the  answer  is 
Yes.  The  procedure  operates  in  conjunction  with  the  LXOR  sam- 
ple program. 
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PROCEDURE  questions 

□DIM  aUESTIDN:STRIHG[6«]i  T: INTEGER?  X,ST0Rft6E!BYTE 
□DIM  fiNSWERiSTRINGtl] 

□FDR  T=1  TD  8 

□READ  aUESTIDN 

DPSIRT  aumiDMi    (Y/W?  "i 

□GET  #B, ANSWER 

□PRINT 

□IF  ASIWEfi*»y"  DR  ANSWER=''Y"  THEN 
nSTIJRA5E»L0R(STDRA6E;i()  C«  Answer  is  yes,  set  bit  to  1. 
□ELSE 

□ST0RAGE=LAND(STDRA6E,LNOTfn)  t»  Answer  is  no,  set  bit  to  i. 

□ENDIF 

□X'XtZ 

□NEXT  T 

□PRINT  STORAGE 

QRUN  suiniiiary(STDRAGE) 

□END 

□DATA  "Do  you'  havs  more  than  one  Color  Computer" 

DDATfl  "Do  you  use  your  Color  Computer  for  games" 

□DATA  "Do  you  use  your  Color  Computer  for  word  processing" 

□DATA  "Do  yaU  llse  your  Color  Computer  for  business  applications" 

□DATA  "Do  you  use  your  Color  Computer  at  home" 

ODATA  "Do  you  use  your  Color  Computer  at  the  office" 

□DATA  "Do  you  use  your  Color  Computer  more  than  two  hours  a  day" 

□DATA  "Do  you  share  your  Color  Computer  with  others" 
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LOG  Returns  natural  logarithm 


Syntax:  LOGinumber) 


Function:  Computes  the  natural  logarithm  of  a  number  that 
is  greater  than  zero.  BASIC09  returns  the  logarithm  as  a  real 
type  result. 

Parameters: 

number  Any  integer,  byte,  or  real  number. 

Examples: 

PRIHT  LDGC3.14159> 
LQGVALUE  -  L0Gt88/PI) 

Sample  Progriimt 

This  procii^tiFe  ealeulates  the  natural  log  aod  tlie  hg  to  base  10 
of  the  v^xm  1-7. 

PROCEDURE  logs 
ODIM  NUM,T: INTEGER 
OFDR  T=1    TD  7 

DPRINT  "The  LOG  of  " ;  T;   "  to  the  natural  base  = 
LDG(T) 

□PRINT  "The  LOG  of  " ;  T;   "  to  base  10  =  " ; 
LDG1 0CT) 
□PRINT 
□NEXT  T 

mm 
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LOGIC  Beiturxis  base  10  logarithm 


Syntax:  LOGlOdiumber) 


Function:  Calculates  the  base  10  l#f  arithm  of  a  numbeir. 
BASIC09  returns  the  logarithm  as  a  real  number. 

Parameters: 

number  Any  hft^,  integier,  or  real  value. 

Examples: 

PRINT  LDG1 0($4B) 
PRINT  L0G1 0(A) 
PRINT  LQG10CA/12) 

Sample  Program: 

This  procedure  calculates  the  natural  log  and  the  log  to  base  10 
of  the  values  1-7. 

PROCEDURE  logs 
□DIM  NUM,T: INTEGER 
DFOR  T-l   TO  7 

DP  I?  I  NT  "The  LOG  of  " ;   T;   "  to  the  nataral  laSe  = 
LDGCT) 

DPRINT  "The  LOG  of  ";   T;   "  to  base  10  =  " ; 
LOilftT) 

□PRINT 
□NEXT  T 
□END 
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LOOP/EjffiLOOP 

Establishes/Closes  a  loop 


Syntax:  LOOP 

statementis) 
ENEffiiOOP 


Function:  Establishes  a  loop  in  which  you  can  install  EXITIF 
tests  at  any  location.  The  LOOP  ai«i  ENDLOOP  statenaents 
define  the  body  of  the  loop.  EXITIP  tests  for  a  coiidititai 

which,  if  TRUE,  causes  alternate  actions,  the  transfer  of  pro- 
cedure execution  to  another  routine,  or  both. 

If  you  do  not  include  an  EXITIF  statement,  the  loop  cannot 
terminate. 

Parameters: 

statement(s)      One  or  more  procedure  lines  to  execute  within 
the  loop. 

Examples: 

LOOP 

COUNT  -  CDUNT+1 

EXITIF  COUNT  >  180  THEN 

DONE  =  TRUE 

ENDEXIT 

PRINT  COUNT 

X-eQUHT/2 

EKDLQQP 

INPUT  X,Y 
LOOP 

PRINT 

EXITIF   X<0  THEN 

PRINT  "X  became  B  first" 

END 

ENDEXIT 

X   =  X-1 

EXITIF  Y=0  THEN 

PRINT  "Y  became  0  first" 
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END 

ENDEX IT 
Y  =  Y-1 
EKDLDQP 

Sample  Program: 

This  procedure  sinmlates  a  gambling  machine  that  awards  cash 
returns  depending  &h  a  ran^m  selection  of  kinds  of  fruits.  You 
begin  with  a  s^&s  $2i  aM  mn.  ot  lose  aceordin^  to  randcnn 
selections  of  the  procedure. 

The  program  uses  LOOP/ENDLOOP  to  keep  operating  until  you 

run  out  of  cash. 

PROCEDURE  bandit 

□DIM  FRUIT1 ,FRUIT2,FRUIT3, STAKE: INTEGER; 
FRUITC1 0):STRING[e] 
□STAKE =25 

□PRINT     \  PRINT  "You  have  $";  STAKE;  "  to  play 
with." 

DFQR  1=1  TD  10 
□READ  FRUITCT) 
□NEXT  T 

□  LDDP 

□FRUIT1 =RND(9)+1  \FRU I T2=RNDC9) + 1  \FRUIT3=RNDC9)+1 
□PRINT  FRUIT(FRUIT1 );   "  ";   FRUITtFRUITS) ;   "  "; 

FRUIT{FRUIT3) 

□  IF  FRUITCFRUIT1  )  =  FRUITCFRUIT2)  AND  F RU I T ( FRU I T1)  = 
FRUIT<FRUIT3)  THEN 

□STAKE=STAKE+1 0 
□ELSE 

□IF  FRUITCFRUITI )=FRUITCFRUIT2)  OR  FRUIT<FRUIT2)= 

FRUIT(FRUIT3)  THEN 

:STAKE=STAKE+2 

□ELSE 

□IF  FRUITCFRUIT1 )=FRUIT(FRUIT3)  THEN 

□STAKE=STAKE+1 
□ELSE  STAKE=STAKE-1 
lENDI F 
□END  IF 
□END IF 

□EXITIF  STAKE<1  THEN 
□PRINT 

□PRINT  "You're  Busted .. .Better  go  home." 


11-85 


BASIC09  Reference 


T:  INTEGER; 


PROCEDURE  questions 
□DIM  QUESTIDN:STRING[60] 
X , STORAGE : BYTE 
DDIM  ANSWER:STRING[1 ] 

nx=-i 

DFOR  T=1    TD  8 

DREAD  QUESTION 

□PRINT  QUESTION;  "  CY/N)?  "; 

□GET  #0, ANSWER 

nPRINT 

DIE  ANSNER="y"  OR  ANSWER="Y"  THEN 

DSTORAGE=LORCST0RAGE,X} 

□ELSE 

□STDRAGE=LftNDCSTORAGE , LNOK  X ) ) 

□ENDIF 
□X=X*2 
QNEXT  T 

□PRINT  STORAGE 

□RUN  summaryCSTORAGE) 

□END 

have  more  than 
use  your  Color 
use 


□DATA   "Do  you 
□DATA  "Do  you 
□DATA  "Do  you 
processing" 
□DATA  "Do  you 
appl icat  ions" 
□DATA  "Do  you 
□DATA  "Bo 
office" 
□DATA  "Do 
two  hours 
□DATA  "Do 
others" 


you 


u.t* 
use 


your 

your 

you  r 
your 


one  Color  Computer" 
Computer  for  games" 
for  word 


Color  Computer 

Color  Computer 


for  business 


Color 
Color 


Computer 
Computer 


at 
at 


home" 
the 


you 


:  your  Color  Computer  more  than 

a  day" 

you  share  your  Color  Computer  with 
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LXOR  Returns  logical  XOR  of  two  numbers 


^^lax:  lXaR(vaiml,mIue2) 


Function:  Performs  the  logical  XOR  function  on  two-byte,  or 
integer-type,  values.  For  instance,  if  you  LXOR  the  nunabers  5 
and  6  the  logic  is  like  this: 

Decimal  5  =  Binary  0101 
Decimal  6  =  Binary  0110 

0101 
LXOR  0110 


0011  =  3  Decimal 

If  one  bit  or  the  other  bit  in  the  evaluation  is  1,  but  not  both, 
LXOR  returns  a  result  of  1,  Otherwise,  LXOR  returns  a 
result  of  0. 

Parameters: 

valml  A  bjrte  or  intega;'  number, 

valu^  A  byte  or  inte^r  nximber. 

Mmmplem 
mtm  Liastn  ,12) 

PRINT  LXOR{$20,$FF) 
Sample  Program: 

The  following  program  summarizes  the  results  of  the  sample 
program  for  LOR.  The  LOR  program  stored  the  answers  to  eight 

questions  in  a  single  byte.  This  procedure  reads  the  byte  and 
displays  appropriate  comments.  LXOR  checks  to  see  if  two  of  the 
answers  £tre  "yes"  or  "no." 
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DENDEXIT 

DPRINT  "Your  stake  is  t\o»  $";  STAKE;  " . " 

□PRINT 
OPRINT 

DINPUf  "Press  ENTER  to  pull  again... ",Z* 

OENDLOOP 
OEND 

□DATA  ■■□RANGE"  ."APPLE",  "CHERRY",  ■■LEMDN"  ,  "BANANA" 
□DATA  "PE  AR"/^PLUM'^,  ■■PEACH",  ■■GRAPE",  ■■APR  I  CQT'^ 
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LOR  Returns  logical  OR  of  two  numbers 


UpLtax:  LORCvaJueijValne^ 


Function:  Performs  the  logical  OR  function  on  a  byte-  or 
integer-type  value.  The  operation  involves  a  bit-by-bit  logical 
OR  operation  on  two  values.  Bbr  instance,  if  jrou  LOR  the 
numbers  5  and  6,  the  logic  is  like  this: 

Decimal  5  =  Binary  0101 
Decimal  6  =  Binary  0110 

0101 
OR  Olio 

=     Dili   =  7  Decimal 

If  one  bit  or  the  other  bit  is  1,  LOR  returns  a  result  of  1. 
Otherwise,  LOR  returns  a  result  of  0. 

Parameters: 

valuel  A  byte  or  integer  number. 

valiie2  A  byte  or  integer  number. 

Estamples: 

PRIST  LB«T1 
PRINT  LORt$20,tFFJ 

Sample  Program: 

This  procedure  stores  the  answers  to  eight  "yes"  or  "no"  ques- 
tions in  one  byte,  named  STORAGE.  If  you  answer  **yes''  to  a 
prompt,  the  procedure  sets  a  corresponding  bit  to  1.  If  you 
answer  "no"  to  a  prompt,  the  procedure  sets  a  corresponding  bit 
to  0.  The  procedure  uses  LOR  to  set  MtB  i&  l  'b^  masking  all  bits 
except  the  one  it  needs  to  set.  The  procedure  operates  in  con- 
junction with  the  LXOR  sample  program. 
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PROCEDURE  summary 

□DIM  T:  INTEGER  ;  A  ,B, )f /Tift  .TEiTgrHfTl ;  SUMMARY! 

STRINGC50 ] 

OPARAM  STDRAGE:BYTE 

nA=0  \B=0 

DPRINT     \  PRINT 

DPRIHT  "The  foUowlTil  la  a  summary  of  the 

questionnaire  answers:" 

□PRINT 

□PRINT  "The  surveyee:  " 
□X»1 

□FOR  T=1   TD  8 

□TEST=LAND(STDRAGE, X) 

□READ  SUMMARY 

OIF  TEST>0  THEN 

DPRINT  TABC10);  SUMMARY 

□ENDIF 

0X=X*2 

□NEXT  T 

Oir  LAND(STQRAGE,128)>0  THEN 

□  A  =  1 
□ENDIF 

□IF  LANDtSTaRAGE,B4)>0  THEN 

□B=1 

□ENDIF 

□TEST2=LXDRCA ,B) 
□IF  TEST2=1  THEN 

□PRINT  "This  computer  owner  either  uses  the 
computer" 

□PRINT  "more   than   two  hours  a  day  or   shares  it 
with  others." 

□PRINT  "This   is  a  heavy  use  situation." 
□END IF 

□TEST2=LANDC A ,B) 
□IF  TEST2=1  THEN 

□PRINT  "This  computer  user  uses  the  computer  more 
than  two" 

DPRIHT  "hours  per  dsy  and  shares  it  with  others. 
This   is  a" 

□PRINT  "super   heavy  use  situation." 

□ENDIF 

□END 

□DATA  "Uses  more  than  one  computer" 
OBATA  "Plays  games" 
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□DATA  "Uses    the   computer   for  word  processing" 

□DATA  "Uses    the  computer  for  business" 

DBATA  "Keeps  a  Color  Computer  at  home" 

□DATA  "Keeps   a   Color   Computer   at    the  office" 

DDATA  "Uses    the   computer  more   than   two  hours 
day" 

□DATA  "Shares   the  computer  with  others" 


MID$  Returns  characters  from  within  a  string 


Syntax:  MID$istring,begin,length) 


FuncMon:  Returns  a  suibstring  length  characters  long,  begin- 
ning at  begin.  Use  MID$  to  "take  apart"  a  string  consisting 
of  a  number  of  elements. 

Parameters: 

string  A  sequence  of  string  type  characters  or  a 

string  type  variable. 

begin  The  position  (an  integer  value)  in  string  of  the 

first  character  to  retrieve. 

hr^th  The  number  of  characters  you  want  to  retrieve. 

Examples: 

NAME$   =   "JONES,    JOHN  M." 
LASTNAME$   =  M I D$ ( N AME $ , 8 , G ) 
FIRSTNAME$   =  MID$(NAME$ , 1 ,S) 
INITIALt  =  MID$(NAME$,1S,2> 

Sample  Program: 

This  procedure  reverses  a  word  or  phrase  you  type.  MID$  reads 
each  character  in  your  phrase  from  the  end  to  the  beginning. 

PROCEDURE  r-everse 

□DIM  PHRA5E:STRING;   T , BEG  I N : I NTEGE R 
□PRINT  "Type   a  word   or    phrase  you   want  to 
reverse:"; 
DPR  I  NT 

UlNPilT  PHtASE 
□BEGIN=LEN(PHRASE) 

□PRINT  "This    is   how  your   phrase    looks  backwards:" 

□FOR  T=BEGIN   TO   1    STEP  -1 

□PRINT  MID$CPHRASE,T,1 )  ; 

□NEXT  T 

□PRINT 

□END 
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MOD  BetimiB  modiihis  of  &  division 


Syntax:  M.GDinumberl,number2) 

Function:  Returns  the  modulus  (remainder)  of  a  division. 
MOD  divides  numberl  by  number2  and  calculates  the  remain- 
der. You  can  use  MOD  to  put  a  limit  on  a  numeric  variable. 
For  instance,  regardless  of  the  value  of  X,  M0D(X,3)  produces 
numbers  only  in  the  range  0  through  2.  M0D(X,5)  produces 
numbers  only  in  the  range  of  0  throvigh  4. 

YovL  can  use  MOD  to  cause  repeating  sequences.  Far  instant, 

in  a  loop,  M0D(X,3)  produces  a  repeating  sequence  of  0,  1,  2, 
where  X  increases  by  1  in  each  step  of  the  loop. 

Parameters: 

numberl         A  bjrte,  Meger  or  real  number  dividend. 
raimber2         A  byte,  integer  or  real  number  divisor. 

Examples: 

PRINT  MDDC99,5) 
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Ssunple  Program: 

This  procedure  uses  MOD  to  execute  repeatedly  routines  that 
display  asterisks  on  the  screen.  There  are  eight  subroutines  that 
the  MOD  function  selects  over  and  over  through  100  passes. 

PROCEDURE  stardown 
□DIM  T: INTEGER 
DSHELL  ••TMDDE  -PAUSE" 

DFOR  T=1    TO  100 
OON  MDDCT,8)+1    GDSUB  1 
□NEXT  T 

DSHELL  "TMQDE  PAUSE" 
□END 

10OPRINT  USING  "SI  0"" 
ZBDPRINT  USING  "SI  0"" 
30DPRINT  USING  "SI  0'*" 
4aaPRINT  USING  "S10"" 
SBOPRINT  USING  «S10»" 

eanPRiNT  using  "si 0*" 

70DPRINT  USING  "S10"" 
80DPRINT  USING  "S10*" 
□END 


0,20,30,40,50,60,70,80 


"»"  \  RETURN 
"»♦"   \  RETURN 
"»•♦"   \  RETURN 
■■»...■■  \  RETURN 
•<•••••••  \  RETURN 

■•»♦.."  \  RETURN 
"»»•"   \  RETURN 
"*»"  \  RETURN 


11-94 


BASIC09  Command  Beference  1 11 


NEXT  Causes  repetition  in  a  FOR  loop 


Syntam    FOR  variable  =  Inlt  vai  1*0  end  va/  [STEP 

value] 

[procedure  statements] 
NEXT  variable 

Function:  NEXT  forms  the  bottom  end  of  a  FOR/NEXT  loop. 
Any  program  statements  between  FOR  and  NEXT  are  exe- 
cuted once  for  each  repetition  of  the  toep,  i&'Con  the  initial 
value  to  end  value. 

Parameters: 

variable  Any  legal  numeric  variable  name. 

init  val  Any  numeric  constant  or  variable. 

end  val  Any  numeric  constant  or  variable. 

value  Any  numeric  constant  or  variable. 

procedure  Procedure  lines  you  want  to  execute  within 
statement       the  h&p. 

For  more  information,  see  FOR/NEXT/STEP. 
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NOT  Returns  the  complement  of  a  value 


Function:  Returns  the  logical  complement  of  a  Boolean  value 
or  expression. 

Parameters: 

value  A  Boolean  value  (True  or  False),  or  an  expres- 

sion resulting  in  a  Boolean  value. 

Examples: 

DIM  TEST:BDDLEAN 
WHILE  NOTCTEST)  DD 
A  =  A  +  1 
TEST=A=B 
ENDWHILE 

Sample  Prf^ams 

This  procedure  redirects  the  current  directory  listing  to  a  file 
named  Dirfile.  It  then  opens  Dirfile  and  reads  the  contents,  dis- 
playing each  line  on  the  screen.  It  uses  NOT  in  a  WHILE/END- 
WHILE  loop  to  make  sure  that  the  end  of  the  file  has  not  been 
tmSmi  belfee  trying  to  r^  amotbet  entry. 

PROCEDURE  readfile 

DDIM  A:STRING[80] 

DDIM  PATH:BYTE 

□SHELL  "DIR   >  dirfile" 

DOPEN  *PATH,"clirf ile":READ 

QWHILE  MOT  ESFCifPATH)  DO 

DREAD  #PATH,A 

□PRINT  A 

DENDWHILE 

□QLDSE  #PATH 

DEND 
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ON  ERROR/GOTO 

Establishes  an  error  trap 


Syntax:     ON  ERROR  [GOTO  Unenma] 

Function:  Sets  bm.  mror  trap  that  transfers  control  to  the  spec- 
ified line  number  in  a  procedure.  This  lets  your  program 
recover  from  an  error  and  continue  execution.  To  use  these 
commands,  your  program  must  have  at  least  one  numbered 
line — ^the  line  to  branch  to  in  the  event  of  an  error. 

Parameters: 

linenum  The  line  to  which  you  want  BASIC09  to 

branch  ^ould  an  error  occur. 

Notes: 

•  ON  ERROR  GOTO  is  effective  only  with  non-fatal,  run- 
time errors.  If  such  an  error  occurs  without  a  preceding  ON 
ERROR  GOTO  statement,  BASICQ9  enters  the  DEBUG 
mode.  You  must  specify  ON  ERROR  GOTO  he&m  m  mm 
occurs. 

•  You  turn  on  error  trapping  by  specifying  ON  ERROR 
GOTO  linenum.  You  turn  off  error  trapping  by  specifying 
ON  ERROR  without  a  line  number. 

•  Use  ON  ERROR  GOTO  with  the  ERR  function  (that 

returns  the  code  of  the  last  error)  to  specify  a  particular 
action  for  a  particular  error.  You  can  also  use  ERROR  to 
simulate  an  error  to  test  error  trapping.  For  more  informa- 
tion on  this,  see  ERROR. 
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DDIM  FILENAME : STRING 
DDIM  PATH : I NTEGER 

10CINPUT  "Name  of  file  to  create?  ".FILENAME 

□ON  ERROR  GDTD  100 

DCREATE  #PATH,FTLEMAME: UPDATE 

□  END 

100DPRINT  "That   file  already  ex  1 s t s  .  .  .  p 1 ea s e 
choose  another  name..." 
QGDTD  10 
OEND 

Sample  Program: 

If  you  created  a  directory  file  with  the  GET  sample  program, 
ymi  can  use  this  procedtire  to  delete  files  from  the  drigjaal  dltec- 
tory  using  key  characters.  For  instance,  you  might  type  XX  as 
key  characters.  This  means  that  any  filename  containing  the 
character  group  XX  is  deleted.  You  can  select  any  key  characters 
you  wish,  but  be  sure  they  apply  only  to  files  you  want  to 
delete. 

If  you  want  to  delete  all  the  files  in  the  directory,  type  an  aster- 
isk (*)  when  asked  for  key  Glmtmim&. 

This  procedure  uses  ON  ERROR  to  let  the  procedure  continue, 
even  if  a  directory  entry  cannot  be  deleted — if  an  entry  is  a  sub- 
directory. Without  the  ON  ERROR  function,  the  procedure 
would  produce  an  error  and  cease  execution  when  it  tried  to 
delete  a  subdirectory. 

PRDCEDURE  purge 

□REM  Use   caution  with   this  procedure 
□REM  Be   sure   to   specify   key  characters 
OREM  that  exist  only  in  the  files  you 
OREM  want  to  delete! 

□DIM  PATH: INTEGER 
□DIM  NAMEd  00)  :STRING 
□DIM  WILDCARD: STRING 

□X=0 

□OPEN  #PATH , "d i r f  i le" : READ 
□WHILE  NDT(EQFC#PATH))  DO 

□X=.X+1 

□READ  iCPATH.NAMECX) 
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□ENDWHILE 
□FOR  T=1    TQ  X 
□PRINT  NAMECT), 
□NEXT  T 

OINPUT  "Wildcard  Characters  ... ".WILDCARD 

□FDR  T=1    TD  X 

□DN   ERROR  GDTD   1 0  0 

□IF  SUBSTRCWILDCARD,NAME(T3)>0  OR  WILDCARD'"*" 
THEN 

DPtlNT  "mX.€Tim       N«Mtm;  "  .  .  " 

□DELETE  NAMEtT) 

□ENDIF 

1  a^NEXT  T 

□END 

100nPRINT  "♦□•□•□ERROR, D"  5  NftMECTJj  'ticannot  be 
deleted.  .  . cont  i  nui  ng . " 
□GOTO  10 
□END 
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ON/GOSUB  «Fuxnps  to  subroutine  on  a 

specified  condition 


Syntax:     ON  pos  60SUB  linmium  Ijlinenum,...] 

Function:  Traasferp  procedure  control  to  the  line  number 
located  at  position  pos  in  the  list  of  line  numbers  immediately 
following  the  GOSUB  command.  For  example,  if  pos  equals  1, 
BASIC09  branches  to  the  first  line  number  it  encounters  in 
the  list.  If  pos  equals  2,  BASIC09  branches  to  the  second  line 
number  it  encounters  in  the  list.  If  pos  is  greater  than  the 
number  of  items  in  the  list,  execution  continues  with  the  next 
command  line.  To  use  ON/GOSUB  you  must  have  numbered 
lines  to  match  the  line  numbers  in  your  list.  End  the  routines 
accessed  by  ON/GOSUB  with  a  RETURN  statement. 

Parameters: 

pos  An  integer  value  pointing  to  a  line  number  in 

a  list  of  line  numbers. 

timnum  Any  numbered  line  in  the  procedure. 

Examples: 

PRINT  "You  can  now:    CI)   End   the  program  (2)  Print 
I  he  rea  B Its" 

PRINT  "  (3)  Try  again  <4>  Start 

a  new  program" 

INPUT  "Type   the   letter   of  your   choice:   ", CHOICE 
ON   CHOICE  GOSUB  100,   200,   300,  400 
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Sample  Program: 

This  procedure  uses  MOD  to  execute  repeatedly  a  sequence  of 
GOSUB  commands.  A  loop  of  index  of  80  causes  execution  to 
jump  to  each  line  number  in  the  list  10  times. 

PROCEDURE  repeat 
DSHELL  "TMODE  -PAUSE" 
ODIM  T: INTEGER 

OFDR  T=1    TO  80 

OON  MaDtT,8)+1    GOSUB  10,20,30,40,50,60,70,80 
DNCXT  T 

□SHELL  "TMODE  PAUSE" 

□  END 


1 0CPR I  NT 

USING 

"SI  0"" 

"♦  " 

\ 

RETURN 

20UPRINT 

USING 

"SI  0"" 

"♦  *" 

\ 

RETURN 

30DPRINT 

USING 

"SI  0*" 

\  RETURN 

40IPRINT 

USING 

"SI  0"" 

"  #  #  » 

»  " 

\  RETURN 

50IPRINT 

US  I  NG 

"SI  0"" 

"  *  «  * 

"   \  RETURN 

60^PRINT 

US  I  NG 

"SI  0"" 

"  *  *  * 

♦  " 

\  RETURN 

70DPRINT 

USING 

"SI  0"" 

"  »  #  * 

II 

\  RETURN 

80nPRINT 

USING 

"SI  0*" 

\ 

RETiiBN 

□END 


11-101 


BASIC09  Reference 


ON/GOTO  Jump  to  line  numb^  on  a 
specified  condition 


%mtax:     ON  pos  GOTO  linenum  [flinemim^...] 

Function:  Transfers  procedure  control  to  the  line  number 
located  at  position  pos  in  the  list  of  line  numbers  immediately 
following  the  GOTO  command.  For  example,  if  pos  equals  1, 
BASIC09  branches  to  the  first  line  number  it  encounters  in 
the  list.  If  pos  equals  2,  BASIC09  branches  to  the  second  line 
number  it  encounters  in  the  list.  If  pos  is  greater  than  the 
number  of  items  in  the  list,  execution  continues  with  the  next 
command  line.  To  use  ON/GOTO  you  must  have  numbered 
lines  to  match  the  line  mmibers  in  the  list. 

Parameters: 

pos  An  integer  value  in  a  range  from  1  to  the 

number  of  items  in  the  list  following  GOTO. 

limimm  Any  numbered  line  in  the  procedure. 

Examples: 

PRINT  "Yoa  can  now:   CI)  End  the  progfaifl  (23  Print 
the  results" 

PRINT  "  (3)  Try  again  (4)  Start 

a   new  program" 

INPUT  "Type  the  letter  of  your  choice:   ", choice 
DN  CHQIO'E  <5DTD  1  00  ,  200,  300  ,  400 

Sample  Program: 

This  procedure  converts  decimal  numbers  to  binary.  It  uses  ON 
GOTO  to  execute  the  operation  you  select  from  a  mi^m:  Convert 
a  number,  display  the  result  of  all  conversions,  or  end  the 
program. 

PROCEDURE  bicalc 

□DIMDNUMBER  ,NUM,X  .STORAGE  i:  I  NTEGERjDB  I  :  STRING; 

□ARRAYC50,2):STRING 

QOOUNT=0 
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10DBI=""   \NUMBER=0    \NUM=0   \X=0  \STaRAGE=0 
□INPUT  "Number   to  convert    to  binary  ", NUMBER 
□IF  NUMBER^B  THEN  END 
nEHBIF 

nHUM=LDG1 0CNUMBER)/.3 
nNUM=2"NUM  \STaRAOE=NUMB£R 
QREPEAT 

□IF  X>0  THEN  BI=Br+"1" 
□NUMBER=MDD<NUMBER,NUM) 
□ELSE  BI=BI+"0" 

□ENDIF 

□NUM=NUM/2 

□UNTIL  NUM<=1 

□IF   NUMBER>0  THEN 

□BI =BI +"1  " 

□ELSE"BI=BI+"0" 

□ENDIF 

□PRINT  STORAGE;   "  =  " ;  BI 5   "  in  binary." 

□PRINT 

□CQUNT=CDUNT+1 

□ARRAY(CD.UNT,1  )  =  STR$CSTDRAGE> 
□ARRAY(CDUNT,2)=BI 

12^PRINT  "Do  you  want   to:   (13  Convert  another 
number  .  " 

□PRINT  "llinilill[Iinil(2)  Display  all  Galculatipns 
thus  far." 

□PRINT  "□□□—--:::::::::(  3)  End  the  program." 
□INPUT  "Enter   1,    2,    or   3 ..,", choice 
□ON  choice  GOTO  10,20,30 

mm 

20^FDR  T=1    TO  COUNT 

□PRINT  ARRAYCT.I);    "   =   ";  ARRAY(T,2) 
□NEXT  T 
□GOTO  12 

SeDPRINT     \  PRINT  "  Program  TBrminated" 
DEND 
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OPEN  Oprnxs  a  path  to  a  device 


Syntax:     OPEN  #patb,"pathlisf'  [access  mode}[+ access 
model[+...] 


Function:  Opens  an  input/output  path  to  a  disk  file  or  to  a 
device.  When  you  open  a  file,  you  can  select  one  or  more  of  the 
following  access  modes: 

Mode  Function 

READ  Lets  you  read  (receive)  data  from  a  file  or 

device  but  does  not  allow  you  to  vsrrite  (send) 
data. 

WRITE  Lets  you  write  data  to  a  file  or  device  but  does 

not  allow  you  to  read  data. 

UraATE        Lets  you  both  read  from  and  write  to  a  file  or 

device. 

EXEC  Specifies  that  the  file  you  want  to  access  is  in 

the  current  execution  dttresstory. 

DIR  %ii@ffl€^  that  the  file  you  vmnt  to  access  is  a 

directory-type  file. 

Parameters: 

path  The  variable  in  which  BASIC09  stores  the 

numbra:  of  the  newly  opened  path. 

pathlist  The  route  to  the  file  or  device  to  be  opened, 

including  the  filename  if  appropriate. 

access  mode  The  type  of  access  the  system  is  to  allow  for 
the  file  or  device.  Use  a  plus  symbol  to  specify 
more  than  one  type  of  access. 
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Notes: 

•  The  access  ix^de  iisBsim  Ibe  direeten  of  I/O  tran^^. 

•  Because  OS-9  files  are  byte-addressed  and  are  unformat- 
ted, you  can  set  up  the  fihng  system  you  want  for  a  partic- 
ular application.  Your  system  can  read  the  data  contained 
in  a  file  as  single  bytes  or  in  groups  of  any  size  you  want. 

•  You  can  expand  a  file  using  PRINT,  WRITE,  or  PUT  state- 
ments to  write  bepaid  the  eurrent  end-of-file. 

Examples: 

□  PEN   #TRANS  /'transportat  ion" : UPDATE 
□PEN   #SP^DL,"/u5er4/report": WRITE 
□PEN  #DUTPATH,name$ :UPDATE+EXEC 


Sample  Program: 

This  procedure  opens  a  path  to  both  the  SYS  directory  on  Drive 
/DO  and  the  error  message  file. 

PROCEDURE  readerr 

IDIM  A:STRING[80] 
ZDIM  PATH:BYTE 

DDPEN   #PATH , "/D0/SYS/ERRMSG" : READ 

□WHILE  EOF(*PATH)<>TRUE  DO 

□READ  -CPATH.A 

□PRINT  A 

DENDWHILE 

□CLOSE  #PATH 

□END 
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OR  Performs  a  Boolean  OR  operation 
^mtax:    op&m^l  OB  apmrndS 

Function:  Performs  an  OR  operation  on  two  or  more  values, 
returning  a  Boolean  value  of  either  TRUE  or  FALSE. 

Parameters: 

operandi         Either  numeric  or  string  values. 
qperarul2 

Examples: 

PRINT  A>3  DR  B>3 

PRINT  fl$-"YES"  or  B«="YES" 


11-106 


BMIC09  Commami  BAmm^  / 11 


Sample  Program: 

This  procedure  asks  you  to  type  a  word  or  phrase,  then  converts 
all  lowercase  characters  to  uppercase.  It  uses  OR  to  test  for  a 
character  in  your  word  or  phrase  that  is  outsiie  of  #i«  ASOII 
values  for  lowercase  letters.  If  it  is,  the  charactra-  does  not  need 
converting. 

PROCEDURE  uppercase 

□DIM  PHRASE, NEWSTRING:STRINGC80] ;  CHfiRACTER; 
STRINGE1 ] ;   T,X: INTEGER 
nNEWSTRING=""  \PHRASE="" 

□PRINT  "Type  a  phrase  in  lowercase  and  I  will  mafce 

it  uppercase." 

□INPUT  PHRASE 

□FDR  T=1   TO  LENCPHRASE) 

□CHAR ACTER=MID$C PHRASE, T,1  ) 

□X=ASC(CHARACTER) 

□  IF   X07  DR   X>122  THEN 

DNEWSTRING=NEWSTRING+CHARACTER 

□ELSE 

tfX  =  X-32 

nNEWSTRING=NE:WSTRING  +  CHR$CX) 

□ENDIF 

□NEXT  T 

□PHRASE =NEWSTRING 
□NEWSTRING="" 
□PRINT  PHRASE 
□END 
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PARAM 

another  procedure 


^ntitax:     PARAM  i^aWeI,...]btj^e][;varfaWe]I,...l[:tjpe] 


Function:  Defines  the  parameters  that  a  called  procedure 
expects  to  receive  from  the  procedure  that  calls  it.  When 
using  PARAM,  be  sure  that  the  total  size  of  each  parameter 
in  the  calling  procedure's  RUN  statement  is  the  same  as  the 
defined  size  in  the  called  procedure's  PARAM  statement. 

mrlmbh  A  mm^  variable,  an  array  steuettir»j  tsr  a 

complex  data  structure. 

type  Byte,  Integer,  Real,  Boolean,  String,  or  user 

defined. 

Notefi 

•  BASIC09  checks  the  size  of  each  parameter  to  prevent  acci- 
dental access  to  storage  other  than  that  assigned  to  the 
parameter.  However,  BASIC09  does  not  check  that  parame- 
ters are  of  the  proper  type.  In  most  cases  you  must  be  sure 
that  types  evaluated  in  RUN  statements  match  the  types 
defined  in  the  lARAM  statements. 

However,  because  BASIC09  does  not  perform  type  checking, 
it  is  possible  to  perform  useful  but  normally  illegal  type 
conversions  of  identically-sized  data  structures.  For  example, 
you  could  pass  a  string  of  80  characters  to  a  procedure 
expecting  a  byte  array  of  80  elements.  Each  character  in 
the  string  is  assigned  a  corresponding  position  in  the 
array. 

•  You  declare  simple  arrays  by  using  the  variable  name, 
without  a  subscript,  in  a  PARAM  statement. 
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•  You  can  declare  several  variables  of  the  same  type  by  sepa- 
rating them  with  commas.  To  separate  variables  of  differ- 
ent types,  follow  each  type  group  with  a  colon,  the  type 

name,  and  then  a  semicolon. 

•  If  you  do  not  include  a  maximum  length  for  a  string  vari- 
able encbsed  in  brackets  followiatf  the  t3^e>  like  this: 

DIM  name:5tring[2S] 

BASIC09  uses  a  default  length  of  32  characters  for  strings. 
You  can  declare  shorter  or  longer  lengths,  to  the  capacity  of 

BASIC09's  memory. 

•  Arrays  can  have  one,  two,  or  three  dimensions.  The 
PARAM  format  for  dimensioned  arrays  is  the  same  as  for 
simple  variables  except  you  must  follow  each  array  name 
with  a  subscript,  enclosed  in  parentheses,  to  indicate  its 
size.  The  maximum  array  size  is  32767. 

Arrays  can  be  either  of  the  standard  BASIC09  type,  or  of  a 
user-defined  type.  To  create  your  own  data  types  for  simple 
variables,  arrays,  and  complex  data  structures,  see  TYPE. 

Examples: 

PARAM  NUMBER : INTEGER 

PARAM  NAME: STRING [25] ; ADDRESS : STR I NG [ 30 ] ;2IP: 
INTEGER 

PARAM  NQI  ,ND2,N03!RESL;N04,NDS,Na6!,INTEQER;NO?: 
BYTE 

Sample  Program: 

The  first  procedure  asks  you  to  enter  a  decimal  number.  Then,  it 
asks  you  to  choose  whether  you  want  to  convert  the  mmiber  to 
binary  cat  hexadecimal.  Depending  on  ybur  choice,  tte  procedure 
calls  (using  RUN)  either  a  procedure  named  Binary  or  a  proce- 
dure named  Hex.  It  passes  the  number  you  typed  to  the  appro- 
priate procedure  for  conversion. 
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PROCEDURE  convert 

DDIM  NUMBER , CHD I CE : I NTEGER 

□PRINT  USING  "S80"";   "Hexadecimal  -  Binary 

Conversion  Program" 

OPRINT 

10DINPUT  "Number  to  conver t NUMBER 
DIE  NUMBER=0  THEN 

DEND 
□ENDIF 

□INPUT  "Ghooae!   (1)  Binary  or  (2)  Hex CHOICE 

OON  CHOICE  GOTO  20,30 
20DRUN  BINARYCNUMBER) 
□GOTO  10 

30DRUN  HEXCNUMBER) 

□GOTO  10 

□END 

PROCEDURE  binary 

DDIM  NUM,X, STORAGE: INTEGER;  BI:STRING; 

ARRAY(50,2):STRING 

DP ARAM  NUMBER: INTEGER 

□CDUNT=0 

DBI=""  \NUM=0   \X=0  \STORAGE=0 

□NUM=L0G1 0(NUMBER)/ . 3 

□NUM=2"NUM  \STORAGE-NUMBER 

□REPEAT 

nx=NUMBER/KUM 

DIF  X>0  THEN 

0BI=BI+"1" 

a:N:UM8ER=M0D<  NUMBER ,  NUM) 
□ELSE 

□BI=BI+"0" 

□ENDIF 

□NUM=NUM/a 

□UNTIL  NUM<=1 

□IF  NUMiER>0  THEN 

□BI=BI+"1'» 

□  ELSE 

□BI=BI+"0" 
DEND IF 

□PRINT  STORAGE;  "  =        BP,  "  in  binary." 

□PRINT 

□END 
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PROCEDURE  hex 

ODIM  HUM, X, STORAGE: INTEGER;   TABLE , HX : STR I NG ; 

ARRAYC50  ,2) : STR I  NO 

□PARAM  NUMBER: INTEGER 

□T  AB  L  E  =  '■  1  234  56789A  BCDEF" 

□HX=""  \NUM=0   \X=0  \5TORAGE-0 

□NUM=LDG1 0C NUMBER) /1 . 2 

□NUM=1G»NUM  \STDRAGE=NUMBER 

DREPEAT 

DX  =  NOM'BER/NUW 

DIF   X>0  THEN 

OHX=HX+MID$(TABLE , X , 1 ) 

DNUMBER=MOD{N UMBER, NUM3 

QELSE  HX=HX+"0" 

DENOfF 

DNUM=NUM/1 6 

□UNTIL  NUM<=1 

□IF   NUMBER>0  THEN 

□HX  =  HX  +  MID$CTABLE, NUMBER, 1  ) 

□EL^E 

□HX=HX+"0" 
□END  IF 

DPBINT  STORAGE;   "  =  " ;  HX;  "  in  hexadecimal." 

DPR  I NT 
DEND 
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PAUSE  Suspmids  execution  and  enters  Debug 


Syntax:     PAUSE  text 

Function:  Suspends  the  execution  of  a  procedure  and  causes 
BASIC09  to  enter  the  DEBUG  mode.  If  you  include  text  with 
the  PAUSE  command,  it  is  displayed  on  the  screen. 

Place  MUSE  statements  in  a  program  temporarily  to  observe 

the  way  in  which  the  procedure  operates  and  to  track  down 
programming  errors.  When  the  procedure  is  operating  cor- 
rectly, remove  the  PAUSE  statement. 

After  using  DEBUG,  you  can  continue  execution  of  the  paused 
procedure  with  the  CONT  command. 

Parameters: 

text  A  message  you  want  PAUSE  to  display  on  the 

screen  when  BASIC09  executes  the  statement. 

Examples: 

PAUSE 

PAUSE  The  array  is  now  fuli. 
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PEEK  Returns  the  value  in  a  memory  location 

%>mtax:  FWmfymmii. 

Function:  Returns  the  value  of  a  memory  byte  as  a  decimal 
integer.  The  value  returned  is  in  the  range  0  to  255.  PEEK  is 
the  comptemeiit  of  the  POKE  statement. 

See  also  ADDR. 
Parameters: 

mem  An  integer  value  representing  the  location  of 

the  memory  byte  you  want  to  examine.  The 
memory  byte  is  relative  to  the  current  pro- 
cess's address  space. 

Examples: 

PRINT  PEEK(1:525  0) 
MEMVAL  =  PEEX(4450) 
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Sample  Program: 

This  procedure  asks  you  to  type  a  phrase  in  uppercase  charac- 
ters. It  then  uses  ADDR  to  locate  the  area  in  memory  where 

BASIC09  stores  the  phrase.  Next,  it  reads  each  character  from 
memory  with  PEEK,  converts  it  to  lowercase  if  necessary,  and 
pokes  the  new  value  back  into  the  same  location.  When  tto  pro- 
cediire  displays  the  contents  of  the  phrase,  it  is  all  low^ase. 

PROCEDURE  lowercase 

□DIM  LaC,T: INTEGER;   PHRASE : STR I NG [ 80 ] 

□PRINT  "Type  a  phrase  in  UPPERCASE  and  I'll  make 

it  lowercase." 

□INPUT  PHRASE 

□LOC=ADDR{PHRASE) 

□FDR  T  =  LDC  TD  L DC  +  L EN C PHRASE  ) 

□X=PEEK(T) 

DIF  X>32  AND  X01  THEN 

D3!  =  X  +  3'2 

□POKE  T,X 

□ENDIF 

□NEXT  T 

OPRINT  PHRASE 

mm 
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PI  Returns  the  value  of  pi 


%ntasE:  PI 

Functioii:  Returns  the  constant  value  3.14159265. 
Parameters:  None 

PRINT  "The  ares  ®f  a  circle  with  a  radius  of  6 
inches  is 

Sample  Program: 

This  procedure  uses  the  formula  (PI  +  2)/15  as  a  basis  for  calcu- 
lating a  screen  position.  Taking  the  sine  of  the  formula,  it  prints 
a  sine  wave  of  asterisks  down  the  screen. 

PROCEDURE  picalc 

□DIM  FDRMULA,CALCULPiTE,PaSITIDN:REAL 
DSHELL  "DISPLffT  0G" 
□FORMULA=(P I +2)/1 5 
□CALCULATE=FDRMULA 
□SHELL   "TMQDE  -PAUSE" 
□FDR  T=0   TD  100 
□CALCULATE=CALCULATE+ FORMULA 
0P0SITIDN=INT(SIN(CALCULATE)»1  0  +  16) 
□PRINT  TABCPOSITION) ;  "»" 
□NEXT  T 

□SHELL  "TMQDE  PAUSE" 
□END 
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POKE  Stores  a  value  in  a  memory  location 


Syntax:     POKE  mem,value 

Function:  Stores  a  value  at  the  specified  memory  address,  rel- 
ative to  the  current  process's  address  space.  Mem  is  an  abso- 
lute address  at  which  BASID09  stares  a  byte  type  -^ue. 
POKE  is  the  complement  of  the  PEEK  statement. 

You  should  use  care  when  using  POKE.  Because  it  changes 
the  value  in  memory,  a  POKE  to  the  wrong  portion  of  memory 
could  cause  OS-9,  BASIC09,  or  your  procedures  to  malfunction 
until  you  reboot  the  system. 

See  also  ADDR. 
Parameters: 

mem  An  integer  value  representing  the  location  of 

the  memory  byte  you  want  to  change. 

value  The  value  to  store  in  the  specified  memory 

locaiatA. 

Examples: 

POKE  15250,13 
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Sample  Program: 

This  procedure  asks  you  to  type  a  phrase  in  uppercase  charac- 
ters. It  then  uses  ADDR  to  locate  the  area  in  memory  where 
BASI009  stores  the  phrase.  Next,  it  reads  each  character  from 
memory,  converts  it  to  lowercase  if  necessary,  and  uses  POKE  to 
store  the  new  value  back  in  the  same  location.  When  the  proce- 
dure next  displays  the  contents  of  the  phrase,  it  is  all  loiwercase. 

PROCEDURE  lowercase 

□DIM  LOC,T: INTEGER;   PHRASE : STR I NG[80 ] 

□PRINT  "Type  a  phrase  in  UPPERCASE  and  I'll  make 

it    1 owercase . " 

□INPUT  PHRASE 

□LDC=ADDRCPHRASE) 

□FOR  T=LOC  TO  LOC+LENCPHRASE) 

□X=PEEKCT) 

□  IF  X>32  AND  X01  THEN 

UX=X+32 

□POKE  T,X 

□ENDIF 

ONE XT  T 

□PRINT  PHRASE 

□END 
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Returns  cursor's  column  position 


Syntax:  POS 

Function:  Returns  the  current  coluiim  posi&n  of  the  curscBr. 

Parameters:  None 

Examples: 

PRINT  PDS 

Sample  Program: 

This  procedure  is  a  simple  typing  program  that  uses  POS  to 
make  sure  that  words  are  not  split  when  you  type  to  the  end  of 
the  screen.  After  you  type  25  characters  on  a  line,  the  procedure 
breaks  the  line  at  the  next  ipaie  eharacter, 

PROCEDUR E  wo  r  dwrap 

□DIM  CHARACTER:STRING[1 ] 

□PRINT  USING  "S32"";   "Word  Wrap  Program" 
□PRINT  USING  "S32*";  "Press  [CTRL] EC]  to  Exit" 

□PRINT 

□SHELL  "TMODE  -ECHD" 
□WHILE  CHARACTERO"  "  DD 
□GET  #1  .CHARACTER 
□PRINT  CHARACTER; 

□IF  P0S>25  AND  CHARACTER="  "  THEN 
DPR  INT  CHRttIS) 

□ENDIF 
□ENDWHILE 

□SHELL  "TMDDE  ECHD" 
□END 
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PRINT  Displays  text 


Syntax:     PRINT  p^iii]  [TAB(|iO£^;l  i£a£a[;data...] 

Function:  Prints  numeric  or  string  data  on  the  video  display 
unless  another  path  is  specified. 

Parameters: 

path  The  number  corresponding  to  an  opened  device 

or  file.  If  you  do  not  specify  path,  the  default 
is  #1,  the  video  screen  (standard  output 
device).  To  print  to  another  device  or  file,  first 
OPEN  a  path  to  that  file  or  device  (see 
OPEN). 

pos  A  column  number  that  tells  TAB  where  to 

begin  printing.  Specify  any  number  from  0  to 
the  width  (£jwa  video  display. 

data  Arsf  nuttieric  or  string  constant  fflc  vaoriable. 

Enclose  string  constants  within  quotation 
marks.  All  data  items  must  be  separated  by  a 
semicolon  or  comma. 

Notes: 

•  If  you  specify  more  than  one  data  item  in  the  statement, 
separate  them  with  commas  or  semicolons. 

•  If  you  use  commas,  PRINT  automatically  advances  to  the 
next  tab  zone  before  printing  the  next  item.  In  BASIC09, 
tab  zones  are  16  characters  ap£u:t. 

•  If  you  use  s^mcolons  or  spaces  to  separate  data  items, 
BASIC09  prints  the  items  without  any  spaces  betweea 
them.  BASIC09  begins  the  next  print  item  immediately  M- 
lowing  the  end  of  the  last  print  item. 

•  If  you  end  a  print  item  without  any  trailing  punctuation, 
PRINT  begins  printing  at  the  beginning  of  the  next  line. 
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•  If  the  data  being  printed  is  longer  than  the  display  screen 
width,  PRINT  moves  to  the  next  line  and  continues  print- 
ing the  data. 

•  TAB  causes  BASIC09  to  begin  displaying  the  specified  data 
at  the  column  position  specified  by  TAB.  If  the  output  line 
is  alreadf  f  i^t  the  specified  TAB  position,  PRINT  ignores 
TAB. 

•  You  can  concatenate  items  for  printing  using  the  plus  (  +  ) 
symbol,  for  example:  print  "hello  "  +  riame$  +  "  " 
+ lastnamet. 

•  PRINT  displays  REAL  numbers  with  nine  or  fewer  digits 
in  regular  format.  It  displays  REAL  numbers  with  more 
than  nine  digits  in  exponential  format.  For  example, 
1073741824  is  displayed  as  1  .  073741 82E+09. 

•  Yon  must  enclose  string  constants  within  quotation  marks. 

ExaiEiftea: 

PRINT  fl* 

PRINT  "Menu  Items" 
PRINT  eOUHT 

PRINT  VALUE,TEMP+Cn/2.5),L0GATIDN$ 

PRINT  #PR INTER—PATH, "The  result   is  "jNUMBER 

PRINT  #DUTPATH  FMT«,GOUNTr VALUE 

PRINT  "what   is"+NAME$+"'s  ape?  "; 

PRINT  "INDEX:  " ;I ;TABC2B) 5 "VALUE !  "jVALUE 
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Sample  Program: 

This  procedure  asks  you  to  type  a  word  or  phrase,  then  displays 
it  backwards  by  reading  each  character  from  end  to  bepnning 
and  using  PRINT  to  dis^^  it  on  the  screen. 

PROCEDURE  reverse 

DDIM  PHRASE, TITLE:STRING;   T , BEG  I N : I NTEGER 
□DIM  INSTRUCTIDNS:STRING[43] 
□TITLE="Word  Reversing  Program" 

□INSTRUCTIONS="Type  a  word  or  phrase  you  want  to 

reve r  5  e :  " 
□PRINT  TITLE 

□PRINT  "  

□WHILE  PHRASEo""  DO 
DPR INT 

□PRINT  INSTRUCTIONS 
□INPUT  PHRASE 
□BEGIN  =  LENCPHi;ASO 

□PRINT  "This  is  how  your  phrase  looks  backwards;" 

□FOR  T=BEGIN  TO  1  STEP  -1 

□PRINT  MID$CPHRASE,T,1 ); 

□NEXT  T 

DPR  I  N  T 

□ENDWHILE 

□END 
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PRINT  USING  Displays  formatted  text 


Syntax:     PRINT  Wpath]  USING  [fyrmat,]  dataUdata...] 


Function:  Prints  data  using  a  format  you  specify.  This  state- 
ment is  especially  useful  for  printing  report  headings, 
accounting  reports,  checks,  or  any  document  requiring  a  spe- 
cific format.  USING  is  actually  an  extension  of  the  PRINT 
statemeiit;  Qm^vs,  ibs  iaiBe  rulis  lhat  apply  to  Vim  FiUNT 
statement  also  apply  to  the  PRINT  USING  statement  (see 
PRINT). 


Parameters: 

path  The  number  corresponding  to  an  opened  device 

or  file.  If  you  do  not  specify  path,  the  default 
is  #1,  the  video  screen  (standard  output 
device).  To  print  to  another  device  or  fUe,  first 
OPEN  a  path  to  that  file  or  device  (see 
OPEN). 

format  An  expression  specifying  the  arrangement  of 

the  displayed  data. 

data  Any  numeric  or  string  constant  or  variable. 

Always  enclose  string  constants  within  quota- 
tion msirks.  Each  data  item  must  be  separated 
by  semicolons  or  commas. 


Notes: 

Each  PRINT  USING  format  specifier  begins  with  a  single  identi- 
fier letter  that  specifies  VSxs  type  of  format,  as  i^iown  in  the  fol- 
lowing table: 

B  Boolean  format 

E  exponential  format 

H  hexadecimal  format 

I  integer  fomoat 

S     string  farmat 
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Follow  the  identifier  letter  with  a  constant  number  that  specifies 
the  field  width.  This  number  indicates  the  exact  number  of  print 
eolttmns  the  output  ocel^pes.  It  must  allow  fto"  hath  the  data  and 
any  overhead  characters,  such  as  sign  characters,  decimal  points, 

exponents,  and  so  on. 

Optionally,  you  can  add  a  justification  indicator  to  the  format 
expression.  The  indicators  are  <,  >,  and  The  meaning  of  these 
indicators  varies,  depending  on  the  format  type  in  which  you  use 
them.  See  the  format  tj^e  descstf  ttitis  for  ifpeeiSg  ij^anation. 

Note:  Do  not  use  any  spaces  within  format  exiwessions. 

The  following  are  the  format  type  descriptions: 

Real 

tte  this  ffflmat  for  real,  integer,  or  "bg^te  type  numbers.  The  total 
field  width  specification  must  include  two  overhead  positions  for 
the  sign  and  decimal  point.  The  field  width  has  two  parts,  sepa- 
rated by  a  period.  The  first  part  specifies  the  integer  portion  of 
the  field.  The  second  part  specifies  how  many  fractional  digits  to 
displ^  to  the  right  of  the  decimal  point. 

If  a  number  has  more  significant  digits  than  the  field  allows, 
BASIC09  uses  the  undisplayed  digits  to  round  the  number 

within  the  correct  field  width. 

The  justification  modes  are: 

<      Left  justify  with  leading  sign  and  trailing  spaces.  This  is 
the  default  if  you  omit  a  justification  indicator. 

>      Right  justify  with  leading  spaces  and  sign, 

"      Right  justify  with  leading  spaces  and  trailing  sign 
(financial  format). 

Some  examples  and  their  results  are: 

PRINT  USING  "R8.2<", 5678. 123  5678.12 

PRINT  USING  "R8.2>",B678.123  5678.12 

PRINT  USING  ■'R8.2>",12.3  12.30 

PRINT  USING  "R8.2>",-555.9  -555.90 

PRINT  USING  "R10. 2*", -6722. 4599  6722.46- 


11-123 


BASIC09  Reference 


Exponential 

Use  this  format  to  display  real,  integer,  or  byte  values  in  the  sci- 
entific notation  format — using  a  mantissa  and  decimal  exponent. 
ThB  field  has  two  parts:  the  first  part  must  altow  for  six  overhead 
positions  for  the  mantissa  sign,  decimal  point,  and  exponent 

characters. 

The  justification  modes  are: 

<  Left  justify  with  leading  sign  and  trailing  spaces.  This  is 
the  default  if  you  omit  a  justification  indicator. 

»      Eight  justify  with  leading  spaces  and  sign- 
Some  examples  and  their  results  are: 

PRINT  USING  "El  2 . 3" , 1 234 . 567         1.235E  +  03 
PRINT  USING  "E13.G>",-. 001234     -1 . 234000E-03 
PilHT  mim-  "O©,,! ^",,1:23456789  1.234S7E+08 

Bilker 

Use  this  format  to  display  integer,  l^e,  rar  real  type  numbers  in 
an  integer  or  byte  format.  The  field  width  must  allow  for  one 
position  of  overhead  for  the  sign. 

The  justification  modes  are: 

<  Left  justify  with  leading  sign  and  trailing  spaces.  This  is 
the  defeult  if  you  omit  a  justification  indicator. 

>      Right  justify  with  leading  spaces  and  sign. 

*     Right  justify  with  leading  sign  and  zeroes. 

Some  escamples  and  their  results  are: 

PRINT  USI NG  "  I4<" , 1 0  10 
PRINT  USING  "I4<",10  10 
PRINT  USING  ■■14"", -10  -010 

H^adecimal 

Use  this  fermat  to  display  any  data  type  in  he^adecinaal  nota- 
tion. The  field  width  specification  determines  the  number  of 
hexadecimal  characters  BASIC09  displays.  If  the  data  to  display 
is  string  type,  this  function  displays  the  ASCII  value  of  each 
character  in  hexadecimal. 
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The  justification  modes  are: 

<      Left  justify  with  trailing  spaces.  This  is  the  default  if 
you  omit  a  justification  indicator. 

>      Right  justify  with  leading  spaces. 

*      Cesater  digits. 

The  number  of  bytes  of  memory  used  to  represent  data  varies 
according  to  data  type.  The  following  chart  suggests  field  widths 
for  specific  data  types: 


Type 


Memory 


Field  Width 
To  Specify 


Boolean  and  Byte 

Integer 

Real 

String 


1 
2 
5 

1  per 
character 


2 
4 
10 

2  times  the  string 
length 


Some  examples  and  their  results  are: 


PRINT  USING  "H4",1 00  0064 
PRINT  USING  "H4",-1  FFFF 
PRINT  USING  "H8"","ABC"  414243 

String 

Use  this  format  to  display  string  data  of  any  length.  The  field 
width  specifies  the  total  field  size.  If  the  strlTig  to  display  is 
shorter  than  the  field  size,  PRINT  USING  pads  it  with  spaces 
according  to  the  justification  mode.  If  the  string  to  display  is 
longer  than  the  specified  field  width,  PRINT  USING  truncates 
the  right  portion  of  the  string. 

The  justification  modes  are: 

<      Left  justify  with  trailing  spaces.  This  is  the  default  if 
you  omit  a  justification  indicator. 

>      Right  justify  with  leading  spaces. 

*      Center  charactws. 
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SMi  ^m-M^m  md  their  results  are: 


PRINT  USING  "S9<", "HELLO- 
PRINT  USING  "S9>","HELLD" 
PRINT  USING  "S9*","HELLD" 


HELLD 

HELLO 
HELLD 


Boolean 

Use  this  format  to  display  Boolean  expression  results.  BASIC09 
converts  the  result  of  the  expression  to  the  strings  "True"  or 
"False."  The  fiffmat  and  results  are  identical  to  OTRING  formats. 
The  justification  modes  are: 

<      Left  justify  with  trailing  spaces.  This  is  the  defeult  if 
you  omit  a  justification  indicator. 

>      Right  justify  with  leading  spaces. 

"      Center  characters. 

If  A  =  5  and  B  =  6,  some  examples  and  their  results  are: 

PRINT  USING  "B9<",A<B  True 
PRINT  USING  "B9>",A>B  False 
PRINT  USING  "B9'"',A  =  B  False 

Control  Specifiers 

You  can  also  use  control  specifiers  within  PRINT  USING  for- 
mats. The  three  specifiers  are: 

Tn  Tab.  n  specifies  a  tab  column  at  which  to  display 


'texf       Constant  string,  text  is  a  string  that  is  constant  to 


An  example  and  its  result  is: 

PRINT  USING  "'Address' , XI  ,H4,X4, 'Data' , XI  ,H2", 
1 000,100 

Addpess  03E8        Data  64 


the  next  data. 


Xn 


Spaces,  n  specifies  a  number  of  spaces  to  insert. 


the  format. 
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Repeat 

You  cam  i'e|>eat  identical  sequences  of  specifications  using  paren- 
theses within  a  format  specification.  Enclose  the  group  of  speci- 
fications you  wish  to  repeat,  preceded  by  a  repetition  count,  such 
as: 

"2(  X2  ,  r1  0.5)"  in  place  of  "X2  ,  R1  0  .  5  ,  X2  ,  R1  0  .  5" 

"'2C  12  ,2(X1  ,S4))"  in  place  of  " 1 2  ,  XI  ,  S4  ,  XI  ,  S4 , 1 2 ,  XI  , 
S4,X1 ,S4" 

Sample  Program: 

This  program  looks  at  memory  locations  32000  to  32010  and  dis- 
plays their  contents  in  decimal,  hexadecimal,  and  binary.  PRINT 
USING  formats  the  display  in  columns. 

PROCEDURE  memlook 

□DIM  NUMBER,!, MEM, VALUE: INTEGER 

DDIM   X ,NUM:  INTEGER;    CH AR ACTER  ,  B I  : STR  I  NG 

□PRINT  "□Addr.nDec.^Hex.DBin^D^D^^ASCI I" 

□FOR  2=32000  TO  32010 

□BI ="" 

□NUMBER=PEEK(Z) 
□IF  NUMBER>0  THEN 
□GDSUB  100 
□END IF 

□IF   PEEK(Z)<32  THEN 

□CHARACTER^"" 
□  ELSE 

□CHARACTER =CHR$CPEEKCZ)) 
DEHDiF 

□IF  PEEK(2)>0  THEN 

□PRINT  USING  "I6<,T7, M<,X2,H4<,X1 ,S8<,X2,S1",Z, 
PEEKCZ),PEEK(Z),BI , CHARACTER 

DILSE  PRINT  USING  " I6< , T7 , I 4< , X2 , H4< , X 1 , S8> , X2 , 
SI", 2, 0,0, "0000","  " 

□ENDIF 
□NEXT  Z 
DEND 
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1 00nNUM=LOG1 0(NUMBER>/.3 

0NUM=2"NUM 

□REPEAT 

DX=NUMBER/NUM 

DIF  X>0  THEN  Bl*il*'M" 

□NUMBER=MaD( NUMBER, NUM) 

DELSE  BI=BI+"0" 

OENDIF 

□NUM=NUM/2 

□UNTIL  NUM<=1 

□IF  NUMBER>0  THEN 

□BI =BI +"1 " 

□ELSE  BI=BI+"0" 

DENDIF 

□END 
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PUT  Writes  to  a  direct  access  ffle 


Syntax:     PUT  ^paim,Mt& 

Function:  Writes  a  fixed-size  binary  data  record  to  a  file  or 
device.  Use  PUT  to  store  data  in  random  accesi  files> 

Although  you  usually  use  PUT  with  files,  you  can  also  use  it 
to  send  data  to  a  device. 

fbr  information  about  storing  data  in  random  access  files,  see 
Chapter  8,  "Disk  Files".  Also,  see  GET,  SEEK,  and  SIZE. 

Parameters: 

path  A  variable  name  you  chose  to  use  in  an  OPEN 

or  CREATE  statement  that  stores  the  number 
of  the  path  to  the  file  or  device  to  which  you 
are  directiag  data. 

data  Either  a  variable  containing  the  data  you 

want  to  send  or  a  string  of  data. 

Examples: 

PUT  #PATH,DATA$ 
PUT  INPUT, ARRAY* 

Sample  Program: 

This  procedure  is  a  simple  inventory  data  base.  You  type  in  the 
information  for  an  itsa  name,  list  cost,  actual  cost,  and  quan- 
tity. Using  PUT,  the  procedure  stores  data  in  a  file  named 
Inventory. 

PROCEDURE  inventory 

□TYPE   !NV_ITEM»NAME:STRIHGC25] ;   L I  ST , COST : REAL ; 
QTY: INTEGER 

□DIM  INV_ARRAYC100j!lNV_ITEM 
ODIM  WDRK—REC:  INV_ITEM 
DDIM  PATHjiyTI 
DON  ERROR  GOTO  1  Z 
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DDELETE  "inventory" 
10DDN  ERROR 

□CREATE  #PATH  ,"invertory" 

QWORK_REC.NAME="" 

□WOtK_REe.LIST=0 

OWDRK_REC . COST=0 

DWDRK_REC . QTY=0 

□FOR  N=1    TO  100 

DPUT  *PATH,WQRK_REC 

ONEXT  N 

□LOOP 

□INPUT  "Record  number?  ",recnum 

□  IF  recnuni<1   DR  recnuni>100  THEN 
□PRINT 

□PRINT  "End  of  Seaaion" 

□PRINT 

□CLOSE  #PATH 

OENB 

□END  IF 

□INPUT  "Item  name?  " ,WaRK_REC . NAME 

□  INPUT  "List  price?  " , WDRK_REC . L I  ST 
□INPUT  "Cost   price?  " , WQRK—REC . COST 

□  INPUT  "Quantity?  « , MOSfCJIEG . STY 
□SEEK  #PATH,(recnum-1 ) •S I ZECWORK_REC ) 
□PUT  #PATH,WORK_REC 

□ENDLDQP 
□END 
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RAD   Returns  tt^^nometric  calculations  in 
radians 


Sjrntax:  RAD 

Function:  Set  a  procedure's  state  flag  so  that  a  procedure  uses 
radians  in  SIN,  COS,  TAN,  ACS,  ASN,  and  ATN  functions. 
Because  this  is  the  BASIC09  default,  you  do  not  need  to  use 
the  RAD  statement  unless  you  previously  used  a  DEG  state- 
ment in  the  procedure. 

Parameters:  None 

Examples: 

RAD 

Sample  Program: 

This  program  calculates  sine,  cosine,  and  tangent  for  a  value  you 
supply.  It  calculates  one  set  of  results  in  degrees,  using  DEG, 
and  the  second  set  of  results  in  radians  using  RAD. 

PROCEDURE  trigcalc 
□ilM  ANGLE 5  REAL 

nam 

niNPUT  "Enter  thi  atigle  af  two  sides  B,f  a 

triangle.  . .".ANGLE 

□PRINT 

OPII  NT  w|llimil»raf  I e "  , " S I NE" ,  "COS  I NE"  ,  "TAN" 

DPR  I  NT  "[miiiiii  -  -  "  -  - 


□PRINT  "Degrees  "  ";  ANGLE , S I NC ANGLE) , COS t ANGLE ) , 
TAN(ANGLE) 

mm 

□PRINT  "Radiana  =  "  ■,  ANGLE  ,  S 1 NC  ANGLE:}  ,  GDSC  ANGLE  >  , 

TANC ANGLE) 

□PRINT 

□END 
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READ  Reads  data  from  a  device  or  DATA, 
statement 


Sjmtax:     BEAD  [#pa^,]  mmame 


Function:  Reads  either  an  ASCII  record  from  a  sequential  file 
or  device,  or  an  item  from  a  DATA  stateaient. 

Parameters: 

path  A  variable  containing  the  path  number  of  the 

file  you  want  to  access.  Yaa  can  also  specify 
one  of  the  standard  I/O  paths  (0,  1,  or  2). 

vamame  The  variable  in  which  you  want  to  store  the 

data  read  from  a  file,  device,  or  DATA  line. 

Itlotesi 

The  following  information  dmls  with  reading  sequential  di^ 
files: 

•  To  read  file  records,  you  must  first  dimension  a  variable  to 
contain  the  path  number  of  the  file,  then  use  OPEN  or 
CREATE  to  opeai  a  file  in  the  READ  or  UPDATE  access 
mode.  The  command  begliis  reading  records  at  tine  first 
record  in  the  file.  After  it  reads  each  item,  it  updates  the 
pointer  to  the  next  item. 

•  Records  can  be  of  any  length  within  a  file.  Make  sure  the 
variable  you  use  to  store  the  records  is  dimensioned  large 
enough  to  store  each  item.  If  the  variable  storage  is  too 
small,  BASIC09  truncates  the  record  to  the  maximum  size 
for  which  you  dimensioned  the  variable.  If  you  do  not  indi- 
cate a  variable  size  with  the  DIM  statement,  the  default  is 
32  characters. 

•  BASIG09  separates  individual  data  items  in  the  input 
record  with  ASCII  null  characters.  You  can  also  separate 
numeric  items  with  comma  or  space  character  delimiters. 
Each  input  record  is  terminated  by  a  carriage  return 
character. 
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The  following  information  deals  with  reading  DATA  itenas: 

•  READ  accesses  DATA  line  items  sequentially.  Each  string 
type  item  in  a  DATA  line  must  be  surrounded  by  quotation 
marks.  Items  in  a  DATA  line  must  be  separated  with 
eomanas. 

•  Each  READ  command  copies  an  item  into  the  specified 
variable  storage  and  updates  the  data  pointer  to  the  next 
item,  if  any. 

•  You  can  independently  move  the  pointer  to  a  selected  DATA 
statement.  To  do  this,  use  line  numbers  with  the  DATA 
lines  See  the  DATA  and  RESTORE  commands  for  more 
information  on  using  this  function  of  READ. 

Examples: 

READ  #PATH,DATA 

READ  #1  ,RESPONSE$ 

READ  #INPUT, INDEX(X) 

FDR  T=1  TD  10 
READ  NAME$(T) 
NEXT  T 

DATA   "J IM" , "JDE" , "SUE" , "T I N A" , "NENDY" 

DATA  "SALL","MICKIE","FRED","MARV","WINNIE" 
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Sample  Program: 

This  procedure  puts  random  values  between  1  and  10  into  a  disk 
file,  then  READS  the  values  and  uses  asterisks  to  indicate  how 
many  times  END  selected  each  ^Itie. 

PROCEDURE  raTirflist 

□DIM  SHOW, BUCKET: STRING 

DDIM  T, PATH, 5ELECTC1 0) ,R: INTEGER 

DBUCKET  =  "♦**•**»»••***»♦»♦**«•*♦ »" 

□FDR  T=1   TO  10 
nSELEfTtT5»0 

□NEXT  T 

□DN  ERROR  GOTO  10 
□SHELL   "DEL  RANDFILE" 
10^ON  ERROR 

□CREATE  #P ATM,  "rm n d f  i  1  e ■' :  U PDATE 

□FDR  T=1    TO  100 
□R=RNDC9)+1 
□WRITE  #PATH,R 
□NEXT  T 

□PRINT  "Random  DistributiQn" 
□SEEK  #PATH,0 
□FDR  T=1    TO  100 
DfiEAD  iPATH,NUM 
□SELECTCNUM)=SELECT(NUM,)  +  1 
□NEXT  T 

□FDR  T=1    TO  10 

□SHOW=RIGHT$CBUCKET,SELECT(T)) 

□PRI NT  US I NG  "S6< , 1 3< , S2 < , S 2 0  <" , "Number " , 

T,":",SHOW 
□NEXT  T 
□CLOSE  #PATH 
□END 
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REM  Inserts  remarks  in  a  procedure 


(*  [iexOC*)] 


Function:  Inserts  remarks  inside  a  procedure.  BASIC09 
ignores  these  remarks;  they  serve  only  to  doctiinent  a  proce- 
dure and  its  functions.  Use  remarks  to  title  a  procedure,  show 
its  creation  date,  show  the  name  of  the  programmer,  or  to 
explain  particular  futures  and  operations  of  a  procedure. 

Parameters: 

text  Comments  you  want  to  include  within  a 

procedure 

Notes: 

•  You  can  insert  remarks  at  any  point  in  a  procedure. 

•  The  second  form  of  REM,  using  parentheses  and  asterisks, 
is  compatible  with  Pascal  programming  structure. 

•  When  editing  programs,  you  can  use  the  es;lamation  char- 
acter "!"  in  place  of  the  keyword  REM. 

•  BASIC09's  initial  compilation  retains  remarks,  but  the 
P\CK  compile  coixacEiand  strips  tlieini  from  proceduires. 

Examples: 

REM   this    is   a  comment 

C*   Insert   text  between  parentheses  and 
asterisks*) 

(*  or  use  only  one  parenthesis  and  asterisk 
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Sample  Program: 

This  procedure  uses  the  various  forms  of  REM  to  explain  its 
operations. 

PRWEBWE  copydir 

□REM  Use  this  program  with  the 

□(♦  GET  sample  program  to  «) 

D('  create  a  file  of  directory') 

Q(«  filenames,  ther  copy  the') 

□(•  files  to  another  directory) 

DDIM  PflTH,T,COUNT:INTEGER;  FILE, JOB, DIRNAME;STRING 

□OPEN  #PflTH,"dirfile";REflD  (•  open  the  file 

QINPUT  "Name  of  new  directory.., 'MJIRNflME  C»  get  the  directory 

nSHELL  "MflKDlR  "tDlRNAME  ('  create  a  newdirectohy 

□SHELL  "LOAD  COPY" 

□HHILE  NOT(EDF(#PATH))  DO 

□READ  #PATH,FILE  (•  get  a  filename 

nJMfLr*^*  'mmm*"/"*nil  t*  create  the  GOP?  SylrtM 

□ON  ERROR  GOTO  18 

□PRINT  "COPY  "i  JOB  (•  display  the  operation 

□SHELL  "COPY  "tJQB  (f  eopy  the  file 

ION  ERROR 

DENDWHILE 

□CLOSE  *PATH 

□END 
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REPEAT/UNTIL 

Establishes  a  loop/Terminates  on  specified  condition 


Syntax:  REPEAT 

procedure  lines 
UNTIL  expression 

Function:  Establishes  a  loop  that  executes  the  encompassed 
procedure  lines  until  the  result  of  the  expression  following 
UNTIL  is  true.  Because  the  loop  is  tested  at  the  bottom,  tiie 
lines  within  the  loop  are  executed  at  least  once. 

Parameters: 

expression       A  Boolean  expression  (returns  either  True  or 

False). 

procedure  Statements  you  want  to  repeat  imtil  expression 
lines  returns  Fklse. 

Examples: 

REPEAT 

COUNT  =  CDUNT+1 
UNTIL  COUNT  >  100 

INPUT  X,Y 
REPEAT 
X    =  X-1 
Y  =  Y-1 

UNTIL  X<1   OR  Y<8 
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Sample  Program: 

The  procedure  sorts  a  disk  file.  In  this  case,  it  is  written  to  sort 
the  diskflle  created  hy  the  GET  sample  progrstna — a  direefewy 
listing.  It  uses  a  REPEAT/UNTIL  loop  to  compare  a  string  in 
the  file  with  the  first  string  in  the  file.  If  the  first  string  is 
greBtee  than  the  comparison  string,  the  procedure  swaps  them. 

PROCEDURE  dirsort 

□DIM  BTEMPsBODLEAN;  TEMP  ,  F I LESC 1 25 ) : STR I NG ;  TOP, 

BDTTDM.M.N: INTEGER 

□DIM  T,X,PATH: INTEGER 

□FOR  T=1   TO  125 

□FILESCT)'"" 

□NEXT  T 

OT-fl 

DQPEN  #PATH,"dirf ile"rREAD 

□PRINT  "LOADING:" 

□WHILE  NOT(EOFC#PATH))  DO 

□T=T*1 

□READ  #PATH,FILESCT> 

□ENDWHILE 

□TOP=T 

□BOTTQM'I 

□PRINT  "SORTING;   " ; 

1 0nN=BDTTOM 

□M=TDP 

□PRINT  "."; 

OLODP 

□REPEAT 

□BTEMP=FILES(N)<FILESCTOP) 
□N=N+1 

□UNTIL  NOTCBTEMP) 
□N=N-1 

□EX ITIF  N-M  THEN 
OENDEX IT 

□TEMP=FILES(M) 

□F I LESCM)=FI LESCN) 

QFILESCN)=TEMP 

DN*N+1 

□EX ITIF  N=M  THEN 
□ENDEX IT 
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□ENDLDDP 

□  IF  NOTOP  THEN 

dlF  FILEStN^OFILESCTOP)  THEN 

□TEMP=FILESCN) 

□FILES(N)=FILES(TOP) 

□FILESCT0P5=TEMP 

QENDIF 

DENDlF 

DTP  B0TT0M<N-1  THEN 

□T0P=N-1 
OGQTD  1 0 
OENDIF 

□  IF  N  +  KTDP  THEN 
□BDTTDM=N+1 
□GDTD  10 
□ENDIF 

□CLOSE  #PATH 

□DELETE  "dirfile" 

□CREATE  #P ATH , "di rf 1 s MR I TE 

□PRINT 

□FDR  2=1    TQ  T 
□WRITE  #PATH,FILESCZ) 
□PRINT  FILESC2), 
DNEXT  Z 

□CLOSE  #PATH 
□END 
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RESTORE  Resets  READ  pointer 


Syntax:     RESTORE  linenumber 

Function:  Sets  the  pointer  for  the  HEAD  cominaiHi  to  the 

specified  line  number.  RESTORE  without  a  line  number  sets 
the  data  pointer  to  the  first  data  statement  in  the  procedure. 

READ  assigns  the  items  in  a  DATA  statement  to  variable 
storage.  When  you  read  an  item,  the  pointer  automatically 
advances  to  the  next  item.  Using  RESTORE  you  can  skip 
backward  or  forward  to  data  items  at  a  specific  line  numb^. 

Parameters: 

linenumber      The  line  number  of  the  DATA  items  you  want 
READ  to  access  next. 

Examples: 

RESTORE  100 

Sample  Program: 

This  procedure  draws  a  box  on  the  screen.  It  uses  RESTORE  to 
repeat  the  data  in  line  20  to  create  the  sides  of  the  box. 

PROCEDURE  box 
□DIM  LINErSTRlN© 

□READ  LINE 
□PRINT  LINE 
□FOR  T=1    TO  10 
□RESTORE  20 
OREAD  LINE 
□PRINT  LINE 
□NEXT  T 
□RESTORE  10 
□READ  LINE 
□PRINT  LINE 

1  0CDATA  ■•  " 

2  0^DATA  "nmmnmnnnnnnnnnmiTn" 

□END 
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RETURN  Returns  from  subroutine 


%ntax:  RETURN 

Function:  Returns  procedure  execution  to  the  line  immedi- 
ately following  the  last  GOSUB  statement. 

Every  subroutine  you  access  with  GOSUB  must  contain  a 
RETURN  statem@ati  %ii  can  qall  a  giilnroatine  in  tMs  man- 
ner as  many  times  as  you  want. 

Parameters:  None 

Sample  Program: 

This  procedure  draws  a  design  of  asterisks  down  the  display 
screen.  It  uses  MOD  to  send  execution  to  a  series  of  PRINT 
USING  routines  over  and  over.  Each  PRINT  USING  routine 
sends  execution  back  to  the  main  routine  with  a  RETURN 
statement. 


PROCEDURE  stars 
QDIM  T: INTEGER 
□SHELL  "TMODE  -PfiUSE" 

DFQR  T=1    TO  100 

DDN  M0DCT,8)+1  GOSUB 

□NEXT  T 

□SHELL  "TMQDE  PAUSE" 
□END 

1 0CPRINT  USING  "SI  0" 
20DPRINT  USING  "SI  0" 
30:PRINT  USING  "S10" 
40uPRINT  USING  "SI  0" 
50DPRINT  USING  "510" 
G0nPRINT  USING  "SI  0" 
70DPRINT  USING  "SI  0"* 

eanpRiNT  using  "Sia* 

□END 


0  ,20 ,30 ,40 ,50 ,G0 ,70 ,80 


\  RETURN 
•♦"   \  RETURN 
•»♦"   \  RETURN 
•»••"   \  RETURN 
•  \  RETURN 

♦•••"   \  RETURN 

\  RETURN 
••"  V  RETURN 
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RIGHT$  Returns  specified  rightmost  portion 
of  a  string 


l^tax:  RlGW£$(Btnttg,lmgai) 


Fiinction:  Returns  the  specified  number  of  characters  fi-om  the 
light  portitm  of  the  specified  sMttg.  If  length  is  fte  same  as  or 
greater  than  the  number  of  characters  in  string,  then  RICrHT$ 
returns  all  of  the  characters  in  the  string. 

Parameters: 

string  A  sequence  of  string  type  characters  or  a  vari- 

able containing  a  sequence  of  string  type 
characters. 

ler^h  The  number  of  characters  you  want  to  access. 

Examples: 

PRINT  RIGHT$C"HDTDQG",3) 
PRINT  RIGHT$CA$,6) 

Sample  ProgyiQat: 

PROCEDURE  lastname 

□DIM  NAMES:STRING;   L ASTN AME : STR I NG C  1  0 ] 
□PRINT  "Here  are  the  last  names:" 
□FOR  1=1   TO  1 0 

mem  NftMEs 

DPDINTER=SUBSTRC"  ".NAMES) 
□PD I NTER=LEN( NAMES) -POINTER 
□LASTNAME=R I GHT$(NAMES, POINTER) 
□PRINT  LASTNAME 
□NEXT  T 

□DATA  "Joe  B 1  o  n  sic  1 "  ,  "Mi  k  e  Marvel", "Hal  Skeemish", 

"Fred  Langly" 

□DATA  "Jane  M i s t y" , "We n dy  Pa s t on" , "Mar t ha 

Upshong" , " Jacquel 1 ne  Rivers" 

EBJATft  "Susy  Reetmore", "Wilson  Creding" 

QEND 
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RND  Returns  a  random  valt^ 


S^ta:iK  MMUmmbmt) 

Function:  Returns  a  random  real  value  in  the  following 

ranges: 

If  number  =  0  then  r£inge  =  0  to  1 

If  numb&-  >  0  then  ras^  =  0  to  number 

The  mlues  produced  by  RND  are  not  truly  random  numbers, 
but  occur  in  a  predictable  sequence.  Specifying  a  number  less 
than  0  begins  the  sequence  over. 

Parameters: 

number  A  niunmc  constant,  variable,  or  repression. 

Examples: 

PRINT  RND<5) 
PRINT  RND<A) 
PRINT  RND(A»SJ 

Sample  Program: 

This  procedure  presents  addition  problems  for  you  to  solve. 
It  uses  RND  to  select  two  numbers  betwem  0  and  20. 


11-143 


BASIC09  Reference 


PRDCEDURE  addition 

□DIM  A,B, ANSWER, C: INTEGER 

□FDR  T=1    TO  5 

□A=RND<20) 

O1-RNBC20) 

□C=A+B 

□PRINT  USING  "'What  i5:D',I3>",A 
□PRINT  USING  '•'□□□□□□□+□',  1 3>",B 

□PRINT  "nnnmnnrri  

□I  HP  UT  '^JllilJUllL!"' ,  WKSWE  R 

DIF  ANSWER=C  THEN 
□PRINT  "CORRECT" 
□  ELSE 

□PRINT  "WRONG" 
□END IF 

□PRINT 
□NEXT  T 
□END 
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RUN  Executes  another  procedure 


^ntam     RUN  ifrocname  lipmfaMi^,p«tmM,„3il 

Function:  Calls  a  procedure  for  execution,  passing  the  speci- 
fied parameters  to  the  called  procedure.  When  the  called  pro- 
cedure ends,  execution  returns  to  the  calling  procedure, 
beginning  at  the  statement  following  the  RUN  statement. 

RUN  can  call  a  procedure  existing  within  the  workspace,  a 
procedure  previously  compiled  by  the  PACK  command,  or  a 
machine  language  procedure  outside  the  workspace. 

Parameters: 

procname  The  name  of  the  procedure  to  execute.  The 
procname  can  be  the  literal  name  of  the  proce- 
dure to  execute,  or  it  can  be  a  variable  name 
containing  the  procedure  name. 

param  One  or  more  parameters  that  the  called  pro- 

gram needs  for  execution.  The  parameters  can 
be  variables  or  constants,  or  the  names  of 
entire  arrays  or  data  structures. 

Notes: 

•  You  can  pass  all  types  of  data  to  a  called  program  except 
bj^e  type.  However,  you  can  pass  hyte  arrays. 

•  If  a  parameter  is  a  constant  or  expression,  BASIC09  passes 
it  by  Maine.  That  is,  BASIC09  evaluates  the  constant  or 
expression  and  places  it  in  temporary  storage.  It  passes  the 
address  of  the  temporary  storage  location  to  the  called  pro- 
cedure. The  called  program  can  change  the  passed  values, 
but  the  changes  are  not  reflected  in  the  calling  procedure. 

•  If  a  parameter  is  the  name  of  a  variable,  array,  or  data 
structure,  BA3IC09  passes  it  to  the  called  program  by  ref- 
erence. That  is,  it  passes  the  acldress  of  the  variable  storage 
to  the  called  procedure.  Thus,  the  value  can  be  changed  by 
the  receiving  procedure,  and  these  changes  are  reflected  in 
the  calling  procedure. 
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•  If  the  procedure  named  by  RUN  is  not  in  the  workspace, 
BASIC09  looks  outside  the  workspace.  If  it  cannot  find  it 

there,  it  looks  in  the  current  execution  directory  for  a  disk 
file  with  the  proper  name.  If  the  file  is  on  disk,  BASIC09 
loads  and  e^1ll@s  it,  regardless  of  wtoethgr  it  is  a  packed 
BASIC09  program  or  a  machine  language  program. 

If  the  program  is  a  machine  language  module,  BASIC09 
executes  a  JSR  (jump  to  subroutine)  instruction  to  its  entry 
point  and  executes  it  as  6809  native  code.  The  machine 
language  program  returns  to  the  original  calling  procedure 
by  ^ecutii^  a  RTS  (retMi  fiwm  subroutine)  instruction. 

•  After  you  c^l  an  m^imaj^  prot^dvtre,  tad  bo  longer  need  it, 
use  KILL  to  remove  it  from  memory  to  free  space  for  other 
operations. 

•  Machine  language  modules  return  error  status  by  setting 
the  C  bit  of  the  MPU  condition  codes  register,  and  hy  set- 
ting the  B  register  to  the  appropriate  error  code. 

Examples: 

RUN  CftLCULATEC10,20,ADD) 
RUN  PRINTCTEXT*) 

Sample  Program: 

Makelist  creates  and  displays  a  list  of  fruit.  Next,  it  asks  you  to 
type  a  ward  to  insert.  After  you  type  and  enter  a  new  word, 
Makelist  uses  RUN  to  call  a  second  procedure  named  Insert  to 
look  through  the  list  and  insert  the  new  word  in  alphabetical 
order.  After  each  insertion,  the  procedure  asks  for  another  word. 
Press  only  |  enter  |  to  terminate  the  program. 

PROCEDURE  makelist 

DD I H  L 1 ST<25 J , NEUORD , TEMPWQRD : STR I NG [  1  S ] 

□DIM  T,LftST: INTEGER 

□LAST=1 0 

□PRINT  "This    i5  your  list..." 

OFOR  T=1   TD  LAST 

□READ  LISTCT3 

□PRINT  LISKT), 

□NEXT  T 

□LOOP 
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OPRINT 
□PRINT 

OINPUT  "Type  a  word  to   iTiser  t  .  .  .  "  ,  NEWORD 

□EXITIF  NEWDRD=""  THEN 

□PRINT 

□END  "I've  ended  the  session  at  your  requeat..," 

□ENDEXIT 

□RUN  InsertCLIST,NEWDRD,LAST) 

□PRINT 

□PRINT  "This  is  your  new  list..." 

□FDR  T=1    TO  LAST 
□PRINT  LIST(T), 
□NEXT  T 
□PRINT 
□EPIDLOOP 

□DATA   "APPLES" , "BAN AN AS" , "CANTALOUPE" 
□DATA   "DATES" , "GRAPES" , "LEMONS" 
□DATA  "MANGOS", "PEACHES", "PLUMS" 
□DATA  "PEARS" 

PROCEDURE  insert 

□PAR AM  L I STC 25 ), NEWORD: STRING! 1 B] 
□PARAM  LAST: INTEGER 
□DIM  TEMPWQRD:STRINGC15] 
□DIM  T,X: INTEGER 

□T=1 

□WHILE  NEWORD>LIST(T)  DO 

□ENDWHILE 

□FDR   X=T  TO  LAST 

□TEMPWDRD=LIST(X) 

□LISTCX)=NEWORD 

□NEWDRD=TEMPWORD 

□NEXT  X 

□LAST=LAST+1 

□LISTCLAST}=NEWORD 

□END 


11-147 


BASIC09  Reference 


SEGK  Resets  the  direct-access  file  pointer 


Syntax:     SEEK  #path,aumber 


Function:  Changes  the  file  pointer  address  in  a  disk  file.  The 
pointer  indicates  the  location  in  a  file  for  the  next  READ  or 
WRITE  operation. 

You  usually  use  SEEK  with  random  access  files  to  move  the 
pointer  firom  one  record  to  another,  in  any  order.  You  can  also 
use  SEEK  with  sequential  access  files  to  rewind  the  pointer 
to  the  beginning  of  the  file  (to  the  first  item  or  record). 

For  information  about  storing  data  in  random  access  files,  see 
Chapter  8,  "Disk  Files."  Also  see  PUT,  GET,  and  SIZE. 

Parameters: 

path  A  ^^iable  name  you  choose  in  which  BASIC09 

gtcnri^  the  number  of  the  path  it  opens  to  the 
file  you  sp©d%. 

number  The  item  or  record  mimber  ym  mnt  to  access. 

If  you  are  rewinding  a  sequential  access  file, 
specify  a  number  of  0. 

Examples: 

SEEK  #PATH,0 
SEEK  #DUTFILE,A 

SEEK  #INDEX ,LaCATION»SIZECINVENTDRY) 
Sample  Program: 

This  procedure  creates  a  file  named  Testl,  then  writes  10  lines 
of  data  into  it.  Next,  it  reads  the  lines  from  the  file  and  displays 
them.  It  uses  SEEK  to  both  store  and  extract  the  lines  in  blocks 
of  25  characters. 
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PROCEDURE  makelines 
□DIM  LENGTH:BYTE 
DDIM  LINE:STRINGC2S] 

□DIM  PPlTH:BYTE 
□LENGTH=25 
□BASE  0 

□DN  ERRDR  GOTO  10 
□DELETE  "teati" 
IBDON  ERROR 

□CREATE  #PfiTH,"teat1":WRITE 

□FOR  T=0  TO  9 

IREAD  LINE$ 

□SEEK  #PATH,LENGTH*T 

□PUT  #PATH,LINE* 

□NEXT  T 

□CLOSE  #PATH 

□OPEN  #PATH,"te5t1 ":READ 
DFOR  T-9  TO  0  STEP  -1 
□SEEK  #PATH,LENGTH*T 
□GET  #PATH,LINE 
□PRINT  LINE 
□NEXT  T 
□CLOSE  *PflTH 
□END 


□DATA 

"Th 

L  5 

1  5 

test 

line 

#1  " 

□DATA 

"Thj 

5 

1  5 

test 

line 

#2" 

□DATA 

"Thi 

5 

1  3 

test 

line 

#3" 

□DATA 

"Th 

5 

i  5 

test 

line 

#4" 

□DATA 

"Th 

5 

i  s 

test 

line 

#5" 

□DATA 

"Th 

S 

i  s 

test 

line 

#e" 

□DATA 

"Thj 

5 

i  5 

test 

line 

*7" 

□DATA 

"Th] 

5 

1  5 

test 

line 

#8" 

IDATA 

"Thj 

5 

1  5 

test 

line 

#9" 

□DATA 

"This 

1  5 

test 

line 

#1  0 
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SGN 

Syntax:  SGNCnumber) 

Fiinctioii:  Determines  whether  a  number's  sign  is  positive  or 

negative. 

If  number  is  less  than  0,  then  SGN  returns  -1.  If  number 
equals  0,  then  SGN  returns  0.  If  number  if  greater  than  0, 
tiien  SGN  returns  1. 

I^rameters: 

number  The  value  for  which  you  want  to  determine  the 

sign. 

Examples: 

PRINT  SGNC-22) 
PRINT  SGN(A) 
PRINT  SGNC44-A) 

Sample  Prograjm: 

1%ds  procedure  uses  SGN  to  create  half  sine  waves  down  the 
screen.  SGN  tests  when  the  SIN  calculation  results  are  positive. 
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PROCEDURE  halfsine 

DBTM  PORMULft  /CftLCULATE .POSITION: REAL 

□  SHELL  "DISPLPlY  0C" 

□FDRMULA=(PI+2)/1 5 

DCALCULATE=FDRMULA 

DSHELL  "TMDDE  -PAUSE" 

Qfm  T»8f  TO  100 

□C AL CUL ATE =CALCUL ATE + FORMULA 

DPOSITIDN= IMTCS I N(CALCULATE)*1 0+18) 

□IF  SGNCSIN(CALCULATE))>0  THEN 

□PRINT  TAB(POSITION) ;  "*" 

OENDIF 

□NEXT  T 

□SHELL  "TMODE  PAUSE" 
□END 
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SHELL  fbrks  another  shell 


Syntax:     SHELL  ["strin^'l + "sMag".,.][  +  variaMe] 
[+  variable...] 


Function:  Executes  OS-9  commands  or  programs  from  within 
a  BASIC09  procedure.  Using  SHELL,  you  can  access  OS-9 
functions,  including  multiprogramming,  utilities,  commands, 
terminal  and  input/output  control,  and  so  on. 

When  you  use  the  ^HELL  command,  OS-9  creates  a  new  pro- 
cess to  handle  the  commands  you  provide.  If  you  specify  an 
operation,  BASIC09  evaluates  the  expression  and  passes  it  to 
the  shell  for  execution.  If  you  do  not  specify  an  operation, 
BASIC09  temporarily  halts,  and  the  shell  process  displays 
prompts  and  accepts  commands  in  the  normal  manner.  In  this 
case,  press  |  gtrl  ||  breakI  to  return  to  BASIC09. 

When  the  shell  process  terminates,  BASIC09  becomes  active 
and  resumes  execution  at  the  statement  following  the  SHELL 
statement. 

Parameters: 

string  Any  OS-9  command  or  function.  String  con- 

stants must  be  enclosed  in  quotation  marks. 
Concatenate  string  constants  and  string  vari- 
ables using  a  plus  symbol  {+). 

variable  Any  string  variable  containing  an  OS-9  com- 

mand or  fanction. 
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SHELL  "CQPY  FILE1  FILE2" 

SHELL  "COPY  FILE1  FILE2&" 

SHELL  "COPY  "+FILE$+"  "*DIRNAME+"/"FILE* 

SHELL  "LIST  DOCUMENT" 

SHELL  "KILL  "+STR${M) 

Sample  Program: 

You  must  use  this  procedure  with  the  GET  sample  progrEon, 
Using  the  two  programs  together  enables  you  to  copy  all  the  flleg 
from  one  dit-eetoiy  to  anomer  directory.  The  GE¥  sataple  pro- 
gram reads  the  files  in  a  directory  and  stores  them  in  a  file 
named  Dirfile.  This  procedure  reads  the  filenames  from  Dirfile 
and  uses  SHELL  to  copy  them  to  the  directory  you  specify. 

PROCEDURE  copyatil 

□DIM  PATH, T, COUNT: INTEGER;  F  I  LE  ,  JOB , P I RNAME : STR I NG 
□OPEN  #PflTH,"dirf i le":READ 

DINPUT  "Name   of   new  d i r ec t or y . . . " , D I RNAME 

□SHELL   "MAKDIR  "+DIRNAME 

OSHELL  "LOAD  COPY" 

DWHILE  NOT<EDFC#PATH))  DO 

DREAD  #PATH,FILE 

GJOB=FILE+"  "+DIRNAME+"/"+FILE 

□ON  ERROR  GOTO  10 

DPilMT  »*CQP¥  JOB 

□SHELL  "COPY  "+JOB 

1 BDDN  ERROR 

□ENDNH I LE 

□CLOSE  #PATH 

□END 
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SIN  Returns  the  sine  of  a  number 


Function:  Calculates  the  trigonometric  sine  of  number.  Yaa 
can  use  the  DEG  or  RAD  commands  to  cause  number  to  rep- 
a  mltie  in  either  degrees  or  radtafii.  Unless  you  specify 
DEG,  the  defeult  is  radians.  SIN  returns  a  real  number. 

BEurameters: 

number  The  angle  ef  two  iides  of  a  trimngk  ^lich 

you  want  to  find  the  ratio. 

Examples: 

PRINT  SIN(45) 

Sample  Program: 

This  procediu'e  calculates  sine,  cosine,  and  tangent  values 
fcff  a  number  you  type. 

PROCrDURt  rat  locale 

□DEG 

□DIM  ANGLE:REAL 

□INPUT  "Enter  the  angle  of  two  sides  of  a 

triangle. . .".ANGLE 

□PRINT 

□  PRINT  "Angle"  ,  "SINE", "CDS  I NE", "TAN" 

□  PRINT  "    


DPRINT  ANGLE, SIN<ANGLE),C0SCANGLE),TAN(ANOLE) 

DPR  I NT 

□END 
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SIZE   Returns  the  size  of  a  data  structure 


Syntax:  SIZE(variaWe) 

Function:  Returns  the  size  in  bytes  trf  a  variable,  array,  or 
data  structure.  SIZE  is  especially  useful  with  random  access 
files  to  determine  tiie  size  of  records  to  store  in  a  file.  You  can 
also  use  SIZE  to  det^ntnine  the  size  of  variable  storage  for 

other  purposes. 

SIZE  returns  the  size  of  assigned  storage,  not  necessarily  the 
size  of  a  string.  Bbr  example,  if  you  dimension  a  variable  for 

15  characters,  and  assign  a  10-character  string  to  it,  SIZE 
returns  15,  not  10.  SIZE  returns  the  total  size  of  arrays.  That 
is,  it  returns  the  number  (rf  el^ents  multiplied  by  the  size  of 
the  elements. 

Parameters: 

variable  The  variable,  array,  or  data  structure  for 

which  you  want  to  find  the  size. 

Examples: 

RECORDLENGTH  »  SIZECA*3 

PRINT  "YOUR  NAME  IS  STORED  IN  A  " ;  SIZECNAME$); 
"  CHARACTER  STRING." 

Sample  Program: 

This  procedure  creates  a  simple  inventory,  stored  in  a 
file  named  Inventory.  It  uses  SIZE  to  calculate  the  size 
of  each  element  to  be  stored  in  the  file,  and  to  move 
the  pointer  to  the  beginning  of  each  record's  storage 
space, 
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PROCEDURE  inventory 

DTYPE  INV_ITEM  =  NAME:STRING[25]  i  L I  ST , COST : RE AL ; 
QTf!lMTE©Efi 

DDIM  INV_ARRAY(100):  INV_ITEM 

□DIM  NORK_REC:  INV_ITEM 
□DIM  PATH:BYTE 
□ON  ERROR  GOTO  10 
DDELETE  "inveTit  ory" 

1 0DDN  ERROR 

□  CREATE  #PATH /"inventory" 
□WORK_REC . NAME="" 
□WORK_REC.LIST=0 
[]WDRK_REe.COST=0 
□NORK_REC . QTY=0 

□FDR  N=1    TO  100 
□PUT  #PATH,WORK_REC 
□NEXT  N 
DLOaP 

□INPUT  "Record  number?  ",recnum 
□IF  recnam<1  OR  recnum>100  THEN 
DPKINT 

□PRINT  "End  of  Session" 

□PRINT 

□CLOSE  #PATH 

□END 

□END IF 

□INPUT  "Item  name?  " , WORK_REC . N AME 

□  INPUT  "List    price?   " , WORK_REC . L I  ST 
□INPUT  "Cost   price?   " , WORK_REC . COST 
□INPUT  "Quantity?  " ,WDRK_REC . QTY 
DSEEK  #PftTW.,Jf8enum-1  )*SIZE<WORK_REC) 
□PUT  #PATH,WORK_REe 

DENDLQOP 
□END 
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Returns  the  value  of  a  number  raised  to  the 
power  of  2 


Syntax:  SQdnunbei^ 


Function:  Calculates  the  value  of  a  number  raised  to  the 
power  of  2. 

Parameters: 

number  The  number  you  want  raised  to  the  power  of  2. 

Examples: 

PRINT  SQ(188) 
PRINT  PI«SQ<R) 

Sample  Program: 

This  procedure  uses  SQ  in  a  formula  that  positions  asterisks  on 
the  screen  in  a  sine  wave  pattern. 

PROCEDURE  sinedown 

□DIM  FORMULA .CALCULATE, POSITION! REAL 

nSHELL   "DISPLAY  0C" 

GFDRMULA=(P I +2)/1 5 

□CALCULATE=FQRMULA 

OSHELL  "TMODE  -PAUSE" 

□FDR  T=0   TO  200 

□C ALC UL ATE = CALCUL ATE +SQ( FORMULA) 
□PDSITI0N=INT(SIN(CALGULftTE)«12+16) 
□PRINT  TABCPDSITION) ;  "♦" 
DNEXT  T 

□SHELL  "TMODE  PAUSE" 

□END 


11-157 


BASIC09  Reference 


/SQRT  Belixms  #xe  square  root  of  a 
number 


%ntax:     SQR(n  umber) 
SQRTdiumber) 


Funetion:  Calculates  Ibe  square  root  of  a  xcuiBib^.  3QE  aai 
SQBT  serve  the  same  fianction. 

l^aranietersf 


Examples: 

PRINT  SQRC188) 
PRINT  PI*SQRT(R) 

i^yeaple  Program: 

This  procedure  uses  SQRT  in  a  formula  to  position  asterisks  on 

the  screen  in  a  sine  wave  pattern. 

PROCEDURE  sqrdown 

DDIM  FORMULA  .CALCULATE, POSITIQNrREAL 
QSHELL  "DISPLAY  0C" 
DFDRWULA  =  PI71S 

□CALCULATE=FDRMULA 
□SHELL  "TMDDE  -PAUSE" 
□FDR  T=0  TO  200 

nCALCULATE=GALCULATE+SQRT(FDRMULA). 
DPOS 1 T  t  ON- 1  mt  S 1  Hi  GALCUL  ATE  1 » 1 2+1  i> 
□PRINT  TAB(PDSITION>; 
□NEXT  T 

DSHtLL  "TMODE  PAUSE" 
□END 


number 


The  number  for  which  you  want  the  square 
root. 
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STEP  Establishes  the  size  of  increments  in  a 
FOR  loop 


Syntax: 

FOR  variable  =  hut  val  TO  end  val  [STEP  value] 
[procedure  stai^ments] 
NEXT  variable 


Function:  STEP  provides  an  increment  value  in  a  FOR/NEXT 
loop.  If  you  io  not  specify  a  STEP  vabm,  the  loop  steps  in 
imamamtm  1^  1. 

BASIC09  executes  the  lines  following  the  FOR  statement  until 
it  encounters  a  NEXT  statement.  Then  it  either  increases  or 
decreases  the  initial  value  by  1  (the  de&ult)  or  by  the  value 
given  by  STEP.  If  you  give  the  loop  an  initial  vjilue  that  is 
greater  than  the  fimtl  -wim,  and  specify  a  negative  value  fer 
STEP,  the  loop  decreases  from  the  initial  value  to  the  end 
value. 

Parameters: 

variable  Any  legal  numeric  variable  name. 

init  val  Any  numeric  constant  or  variable. 

end  val  Any  numeric  constant  or  variable. 

value  Any  numeric  constant  or  variable. 

procedure  Procedure  lines  you  want  to  be  executed 
statements        within  the  loop. 
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Example 

FDR  COUNTER  =  1    to  100  STEP  .5 
PRINT  COUNTER 
NEXT  COUNTER 

FDR  X  =  10  TO  1   STEP  -1 

PRINT  X 
NEXT  X 

FOR  TEST  =  A  TO  B  STEP  RATE 
PRINT  TEST 
NEXT  TEST 

Sample  Program: 

This  prdcedill-e  reverses  the  order  d  characters  iii  a  msd.  m 
phrase  you  type.  It  uses  STEP  to  decrement  a  counter  that 
points  to  each  character  in  the  string  in  reverse  order. 

PROCEDURE  reverse 

DDIM  PHRASE:STRING;  T, BEGIN: INTEGER 
OPRINT  "Type  a  word  or  phrase  you  want  to 
reverse : " ; 

□PRINT 

DINPUT  PHRASE 
DHEGIH'LENCPHtASE) 

□PRINT  "This   is  how  your  phrase  looks  backwards;" 

□FOR  T=BEGIN  TO  1   STEP  -1 

□PRINT  MID$CPHRASE,T,1 ); 

□NEXT  T 

OPRINT 

DEND 
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STOP  Terminates  a  procedure 


Syntax:     STOP  ["string'] 

Function;  Causes  a  prbcedure  to  cease  execution,  print  the 
message  "STOP  Encountered",  and  return  control  to 
BASIC09's  command  mode.  You  can  also  specify  additional 
text  to  display  when  BASIC09  encounters  STOP. 

Use  stop  when  you  want  a  procedure  to  terminate  without 
entering  the  DEBUG  mode. 

Parameters: 

string  lesA  to  display  wheai  STOP  executes. 

Examples: 

STOP  "Program  terminated  before  completion." 

IF  RESPONSE  =  "Y"  THEN  STOP  "Program  tarminated 

at  your  request . " 

ENDIF 
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Syntax:  STR$inumber) 


Function!  Coiwerts  a  numeric  type  to  a  stiitig  type.  Hiis  lets 

you  display  the  number  as  a  string  or  use  string  operators  on 
a  number.  The  conversion  replaces  the  numeric  values  with 
the  ASCII  characters  of  the  numbOT.  STR$  ia  the  inverse  of 
the  YAL  function. 

Parameters: 

number  Any  numeric-type  data. 

Examples: 

PRINT  STR$(1 01 0) 

DIM   I  :  INTEGER 
1=44 

PRINT  STRItlJ 

DIM  B:BYTE 
B=001 

PRINT  STR*tB> 

DIM  R:REAL 
R=1234.5e 
PRINT  STR$CR> 

Sample  Program: 

This  procedure  calculates  an  exponential  value,  then  adds  the 
necesisary  number  of  zeroes  to  convert  it  to  standard  notation.  It 
meB  &tB$  to  emWt  tiie  number  you  l^pe  to  a  sti^i^  t^e  ^ue 
so  that  it  can  use  string  functions  to  add  the  zeroes. 
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PROCEDURE  bignum 

□DIM  C, PLACES, B,SIGN:STRING;  EX .COUNT , NEWCDUNT , 
DECIMAL: INTEGER 

□DIM  NEW, ZERO, NEWEST :STR I NGE1 00] 

□CDUNT=-1 

□ZERD="0 000 00000 000000000000000000000000000" 
□NEW=""  \NEWEST="" 

QINPUT  "What  numiaer  do  you  want  to  raise  to  the 

power   of   14?...",  NUM 

□A'NUM"!  4 

QB»iTi$Cft5 

DEX-SySSTRC"E",B) 

□SIGN=MID$(B,EX  +  1  ,1  ) 

□PLACE5=RIGHT$CB,LEN(BJ-EX-1 ) 

□FDR  T=1    TO  LEN(B) 

De=MID»CB,T,1 ) 

□IF  C="."  THEN 

□DECIMAL=0 

□GDTD  10 

□ENDIF 

□DECIMAL»DECIMAL+1 
□IF   C="E"  THEN  100 

□NEW=NEW+C 
1 aiNEXT  T 

1 0  0^NEWCOUNT=VALCPLACES) -DECIMAL 
□NEW=NEW  +  LEFT*CZERD,NEWCDUNT+1  ) 

□FDR  T=LENCNEW)  TO  1   STEP  -1 
□CDUNT=CDUNT+1 

□NEWEST=MID*CNEW,T,1 )+NEWEST 
QIF  MDDCCDUNT,3)=2  AND  T>1  THEN 
ONEWEST=","+NEWEST 

□ENDI F 
□NEXT  T 

DPRrNT  mm%  "  to  the  power  of  14  -  a 

OPRINT  "=  NEWEST 

DENIS 
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Searches  for  specified  characters  i 
a  string 


ui 


g^tax:  BliBSTMtarge^MngfSearehstriBg) 


Function:  Searches  for  the  first  occurrence  of  targetstring 
within  searchstring  and  returns  the  numeric  value  of  its  loca- 
tion. SUBSTR  counts  the  first  character  in  searchstring  as 
character  Number  1.  Therefore,  if  you  searched  for  the  string 
"wOTth"  in  toe  sMog  ^fctwcrth'',  SUBSTR  rekams  a  vaike  of 
5. 

If  SUBSTR  cannot  find  targetstring,  it  returns  a  value  of  0. 
Piarametra:^ 

targetstring      The  group  of  characters  you  want  to  locate. 


Examples: 

PRINT  SUBSTRC "THREE", "ONETWDTHREEFDUBF IVES IX") 
X=SUBSTRC"  ",FULLNAME$) 

Sample  Program: 

This  procedure  selects  the  last  name  from  a  string  con- 
taining both  a  first  name  and  a  last  name.  It  uses 
SUBSTR  to  find  the  space  between  the  two  names  in 
order  to  determine  where  the  last  name  begins. 


The  string  in  which  you  want  to  find 
targetstring. 
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PROCEDURE  lastname 

□DIM  NAMES:STRING;   L ASTN AME : STR I NG [ 1 0 ] 
□PRINT  "Here  are  the  last  names:" 

□FDR  T=1    TD  10 
□READ  NAMES 

nPOINTER=SUBSTRC"  ", NAMES) 
□PO I NTER=LENC NAMES) -POINTER 
□L  flSTN  AME     f©HTf  C  N  m&  S Pfl  I  NtE  fS  J 
□PRINT  LASTNAME 
□NEXT  T 

□DATA  "Joe  lions k  i"  , '"Mi fee  MarveT'/'Hal 
Skeeraish", "Fred  Laung ly" 

□DATA  "Jane  Mi  sty" , "Wendy  Pa s t on" , "Mar t ha 

Up  5  ho n g "  ,  " Ja c q u e 1 i ne  Rivers" 

□DATA  "Susy  Reetmore" , "Ni 1  son  Creding" 

□END 
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SYSCALL  Executes  an  OS-9  System  Call 


Syntax:     SYSCALL  callcode  registers 

Function:  Lets  you  execute  any  OS-9  system  call  fmm 
BASIC09.  Use  this  command  to  directly  manipulate  your  sys- 
tem or  data  or  to  directly  access  devices. 

Be  careful!  Used  improperly,  SYSCALL  can  cause  undesira- 
ble results — you  might  unintentionally  format  a  disk  or 
destroy  disk  or  memory  data.  Before  using  SYSCALL,  you 
should  be  familiar  with  assembly  language  programming  and 
should  understand  the  system  call  information  in  the  OS-9 
Technical  Reference  manual.  The  OS-9  Technical  Reference 
manual  provides  information  about  all  OS-9  system  calls. 

To  pass  required  register  values  to  the  SYSCALL  command, 
create  a  complex  data  structure  that  contains  values  for  all 
registers.  For  example: 

TYPE  REGISTERS=CC,A,B,DP:BYTE;    X , Y , U : I NTEGER 
DIM  REGS : REGISTERS 
DIM  CALLCDDE:BYTE 

The  complex  data  type  REGISTERS  contains  values  for  all 
registers.  Unless  you  specifically  assign  values  to  variables 
(for  instance,  REGS.CC,  REGS.A,  and  REGS.B  in  the  pre- 
vious example),  they  contain  random  values.  See  the  TYPE 
eommand  for  further  information. 

Parameters: 

callcode  is  the  request  code  of  the  system  call  you  -wish 

to  use.  All  system  call  codes  are  referenced  in 
the  OS-9  Technical  Reference  manual. 

registers  is  a  list  of  the  register  entry  values  required 

for  the  system  call  yoa  »e  t^iag. 

Examples:    see  "Sample  Programs." 
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Sample  Programs: 

The  following  programs  set  up  a  data  type  (REGISTERS)  for  the 
register  variables.  Before  executing  SYSCALL,  the  procedures 
store  the  required  register  entry  values  in  the  complex  data 
structure  REGS.  The  procedures  also  establish  CALLCODE  as  a 
variable  to  hold  the  request  code  of  the  system  call  you  want  to 
use. 

The  Writecall  procedure  uses  the  string  variable  TEST  to  store 
text  that  it  writes  to  the  screen  through  Path  0  (the  standard 
output  path)  using  System  Call  $8A,  I$Write.  Before  the  proce- 
dure calls  I$Write,  it  stores  the  appropriate  path  number  (0)  in 
Register  A.  *fh&  ADDR  command  calculates  the  address  of  the 
variable  TEST,  and  the  LEN  command  determines  the  length  of 
the  variable.  The  procedure  stores  these  two  values  in  Registers 
X  and  Y. 

The  Readcall  uses  System  Call  $8B,  I$ReadLn  to  perform  a 
function  that  is  the  opposite  of  Writecall,  Readcall  establishes 
TEST  as  a  string  variable  irtto  '\fMth.  It  writes  the  characters 
you  type.  Because  the  length  of  TEST  is  restricted  to  ten  charac- 
ters (DIM  TEST :  STR I NG [  1 0  ]),  the  terminal  bell  sounds  if  you 
attempt  to  type  more  than  10  characters.  Pressing  [ENTER] 
terminates  the  call  and  the  procedure  prints  the  contents  of 
TEST — the  characters  you  typed. 


11-167 


BASIC09  Reference 


PROCEDURE  WriteCall 

tlTYPE  REi5 1 STERS-CC  ,  A  ,  B ,  BP ;  lYTE ;  X  ,  Y ,  U :  I MTEGER 

□DIM  REGS:REGISTERS 
□DIM  PATH,CALLCODE:BYTE 
□DIM  TESTrSTlIMBCCg] 

□TEST="Thls  is  a  teat  of  IJWrite,  System  call 
$8A.  .  ." 

□REGS  .  Pl  =  0 

□REGS.X=ADDRCTEST) 
DRESS. Y=L EN « TEST) 

DCALLCDDE=$8A 

□RUN  SYSCALLCCALLCDDE.REGS) 

□PRINT 

□END 

PROCEDURE  Readcall 

□TYPE  REGISTERS  =  CC,A,B,DP:BYTE;    X  ,  Y  ,  U :  I NTEGER 
□DIM  REGS:REGISTERS 
□DIM  PATH,CALLCQDE:BYTE 
□DIM  TEST:STRING[1 0] 
□REGS . A=0 

□REGS . X=ADDR(TEST) 
□REGS. Y=1 0 
□CALLCDDE=$8B 

□RUN  SYSCALLt  C  ftLL  COM ,  REGS  J 

□PRINT 
□PRINT  TEST 
□END 
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TAB  Causes  PRINT  to  jump  to  the  specified 
column 


^mtax:  TABinumber) 

Function:  Causes  PRINT  to  display  the  next  PRINT  item  to 
display  in  the  column  specified  liy  number.  If  the  cursor  is 
already  past  the  desired  tab  position,  BASIC09  ignores  TAB. 

Use  POS  to  determine  the  current  cursor  position  when  dis- 
playing characters  on  the  screen. 

Screen  display  columns  are  numbered  from  1,  the  leftmost  col- 
umn, to  a  maximum  of  255.  The  size  of  BASIC09  output 
buffer  varies  according  to  the  stack  size. 

Yon  can  also  use  TAB  with  PRINT  USING  statements. 
Parameters: 

number  The  column  at  which  you  want  PRINT  to 

begin. 

Examples: 

PRINT  TABt20);TITLE$ 

PRINT  TAB<3(  j  ;  ITEMHUMBER;  ITEM* 

Sample  Program: 

This  procedure  uses  asterisks  to  simulate  a  sine  wave  on  the 
screm.  It  vms  TAB  to  position  eaa^  asterisk  in  the  proper 
location. 
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PROCEDURE  slnevKave 

DDIM  FORMULA , CALCULftTI.POSITIONsREflL 

nSHELL  "DISPLAY  0C" 
□FDRMULA=(PI+2)/15 
DCALCULATE=FDRMULA 
aSHEl-L  "TMODE  -PAUSE" 
CfFOR  T=0  TO  2  00 

DC  ALCUL ATE  =  CALCUL ATE +  SQC FORMULA) 
DPOS  I TI  0N=  INKS  I  N(  CALCULATE)  ♦12  + 16} 
□PRINT  TABCPOSITIDN)!  "•" 
QNEXT  T 

□SHELL  "TMDDE  PAUSE" 
□END 
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TAN  Returns  the  tangent  of  a  value 


Syntax:  TANinumber) 

Function:  Calculitttei  the  trigonometrtc  tangent  of  number. 
Using  DEG  or  RAD,  you  can  specify  the  measure  of  the  angle 
{number)  in  either  degrees  or  radians.  Radians  are  the  default 
units. 

Parameters: 

number  The  angle  for  which  you  want  to  find  the 

tangent. 

Examples: 

PRINT  TAN(45) 

Sample  Program: 

This  procedure  calculates  sine,  cosine,  and  tangent  values  for  a 

number  you  type. 

PROCEDURE  ratiocalc 

mm 

mm  AN©kf  iPEAL 

□  INPUT  "Enlel*  the  angle  of  two  sides  fif  a 

triangle.  ANGLE 

□PRINT 

□PRI NT  ••Angle" , "S I NE" , '•CDS I NE'^ , "TAN^* 

□PRINT  ••--    


□PRINT  ANGLE.S I Nt ANGLE), CDS( ANGLE ),TANt ANGLE > 

□PRINT 
□END 
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TRIM$  Removes  spaces  from  the  end  of  a  string 


Syntax:  TRlMUstring) 


Function:  Btemoves  any  trailing  spaces  from  the  end  the 

specified  string.  This  function  is  particularly  useful  for  trim- 
ming records  you  recover  from  a  random  access  file. 

I^ameters: 

string  The  string  or  string  variable  from  which  you 

wish  to  remove  trailing  spaces. 

Examples: 

PRINT  TRIM$<A*) 

GET  A$ ,B$ ,C$ 

PR  INT  TRIM$CA$) ,TRIM$(B$) ,TRIM$CC$) 

Sample  Program: 

This  prograa  takes  names  you  type  and  puts  them  in  a 
random  access  disk  file.  Because  random  access  files  use 
the  same  amount  of  storage  for  each  item,  short  names 
are  padded  with  extra  spaces.  When  reading  the  names 
back  from  the  file,  the  procedure  uses  TRIM$  to  remove 
these  extra  spaces. 

PROCEDURE  Tiamestor 

DDIM  NAMES, TEMPI,  .NfiMECI  (30)  :STRIN0i:26]  ;   FIRST, LAST: 

STR I  NO  C 1 5 1 5    I  N IT  r  AL : STB  I NG  C 1  ] 

□DIM  PATH, T: INTEGER 

nNAMES="" 

ODN  ERROR  GOTO  1 S 

DDELETE  "nameiist" 

IBDDN  ERROR 

□CREATE  #PATH  ,"nameli5t":UPDATE 

OFDR  T=1    TO  100 

□NAMECT)="" 

□NEXT  T 

DT-f 
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DLDDP 

DINPUT  "First   Name:  ".FIRST 
□EXITIF  FIRST-""  THEN 
OCLQSE  #PATH 
000X0  108 
DENDEXIT 

□INPUT  "Initial:  ".INITIAL 
OINFUT  "Last:  ".LAST 

□T=T+1 

□NAME<T)=FIRST+"  "+INITIAL+"  "+LAST 

□PUT  #PATH,NAME(T) 
□SEEK  #PATH,T»2e 
□ENDLDDP 

1 00IOPEN  #PATH ,"namelist":READ 

□PRINT     \  PRINT 

□  PRINT  "Lastname" , "Fi  rstname" , " I ni  t  ial" 
□REM  Print   underline   (40  characters) 

□PRINT  "  

□PRINT 

□SEEK  #PATH,0 
□T  =  0 

□while  ndt(edf(#path>)  do 
□get  #path, names 

:t=t+i 

INAMES=TRIM$CNAMES) 

□X=SUBSTR("  ".NAMES) 

□FIRST=L£FT»CNAMES,X-1 ) 

□TEMP 1 =R I GHT$  C  N  AMES , L  EN  t  N  AMES ) -  X  + 1 3 

□  INITI  AL  =  MID$(TEMP1  ,2,1) 

□LAST  =  RIGHT$CTEMP1  .LENCTEMP1 )-3) 

□Pi  I  NT  LAST ,  F I RST ,  I N I T I A  L 

□SEE*?  #PATH,T«2e 

□ENDWHILE 

ICLDSE  (CPATH 

□END 
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TRON/TROFF  Tums  on/off  trace  function 


Syntax:  TRON 
TROFF 


Function:  Turns  on  or  off  the  BASIC09  trace  mode.  When 
trace  is  turned  on  (TRON),  BASIC09  decompiles  and  displays 
each  statement  in  a  procedure  before  execution.  BASIC09  also 
displays  the  result  of  each  expressiiw  after  evaluation.  This 
function  lets  you  fellow  program  flow  and  is  helpful  in  debug- 
ging and  analyzing  the  execution  of  a  procedure.  After  the 
procedure  is  debugged,  remove  the  TRON  statement. 

If  you  want  to  view  only  a  portion  of  a  procedure's  execution, 
surround  that  portion  with  TRON  and  TROFF.  Tracing 
begins  inunediately  after  the  TEQN:  statement  and  ends  at 
the  *PEdi*F  statement.  The  rest  of  the  program  executes 
normally. 

Parameters:  None 

Examples: 

B$°"0000I9000  0  000  00  0  0I90  00"+B$ 

N-1  +LE'NCB*> 

FOR   1=4  TD  1   STEP  -1 

TRON 

N-N  4 

ACI)-VALCMID$CB$,N,4)> 

TROFF 

NEXT  I 
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TRUE  Betimis  a  Booleaii  TWSM  value 


Syntax:      variable = TRUE 

Function:  TRUE  is  a  Boolean  function  that  always  returns 
True.  You  can  use  TRUE  and  EfUiSE  to  assign  values  to  Boo- 
lean variables. 

Parameters: 

variable  The  Boolean  storage  unit  you  want  to  set  to 

True. 

Examples: 

DIM  TESTrBDOLEAN 
TEST=TRUE 

Sample  Program: 

This  procedure  asks  five  questions.  If  your  answer  is  correct,  it 
stores  the  Boolean  value  TRUE  in  a  Boolean  type  variable.  If 
your  answer  is  incorrect,  it  stores  the  Boolean  value  ElULiSE  in 

the  variable. 

PROCEDURE  quiz 

□DIM  RePLY.VALUEiBOQLEAN;  ANSWER : STRING[ 1 ] ; 
QUESTION : STRINGC80] 

□FDR  T=1    TO  5 

□READ  QUESTION .VALUE 

□PRINT  QUESTION 

□PRINT  "CTJ  =  TRUEULUULtDCF)  -  FALSE- 
SPRINT  "Select  T  or  FsDD"; 
□GET  #1 , ANSWER 
□IF  ANSWER="T"  THEN 
□REPLY=TRUE 
□ELSE 

□REPLY=FALSE 

□ENDIF 

□IF  REPLY=VALUE  THEN 

□PRINT     \  PRINT  "That's  Co r r ec t  .  .  . Good  Showl" 
OELSE 
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□PRINT  "Sorry,  you're  wrong ...  Bet t er  Luck  next 
time." 

□ENDIF 

□PRINT     \  PRINT     \  PRINT 
□HE XT  T 

□DATA  "In  computer   talk,   CPU  stands  for  Central 
Packaging  Unit.",  FALSE 

□DATA  "The  actual  value  of  64K  is  6SS36 

byteg.".TR]LlE 

□DATA  "The  bits  in  a  byte  are  normally  numbered  0 
through  7.", TRUE 

□DATA  "BASIC09  has  four  data  types .", FALSE 
□DATA  "The  LAND  function  is  a  Boolean  type 
operator .".FALSE 
□END 
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BdObaes  a  data  type 


Syntax:     TYPE  name  =  typedeclar  [;typedeclaii;...]] 

FimcMon:  D^nes  new  data  types  (comptex  data  staictttres). 

New  data  types  are  vectors  (one-dimensional  arrays)  of  previ- 
ously defined  types.  Structures  created  by  TYPE  differ  from 
arrays  in  that  they  can  consist  of  elements  of  different  types, 
and  BASIC09  accesses  elements  by  field  names  rather  than  by 
an  indexed  position. 

Parameters: 

name  The  name  you  select  for  the  new  data  type. 


•  Comples  data  structures  allow  you  to  create  data  types  that 
are  appropriate  for  a  specific  task.  You  can  organize,  read, 
and  write  associated  data  naturally.  Also,  BASIC09  estab- 
\i^m  and  defines  element  podtions  at  compilation  time. 
This  saves  time  and  overh^sad  at  run  time  lieeaase 
BASIC  09  can  access  the  elements  of  a  data  structure  &st^ 
than  it  can  access  the  elements  of  an  array. 

•  When  you  define  new  data  structures  using  TYPE,  you  can 
include  any  of  the  five  existing  data  types  (string,  real, 
integer,  byte,  and  Boolean),  or  you  can  include  data  struc- 
ture types  that  you  previously  defined  with  TYPE,  This 

means  that  your  structures  can  be  simple  or  very  camplsx, 
such  as  non-rectangular  data  lists  or  trees. 

•  TYPE  does  not  create  storage.  You  create  storage  using  the 
DIM  statement,  after  using  TYPE. 

•  To  access  elements  of  a  data  structure,  use  the  field  name 
as  well  as  any  appropriate  element  index. 


typedeclar 


One  or  more  type  declarations,  which  can  con- 
sist of  field  names,  type  declarations,  and  sub- 
scripts. Separate  different  types  or  different 
lengths  of  string  declarations  with  semicolons. 


Notes: 
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•  For  more  information  on  creating  and  using  complex  data 
types,  see  "Complex  Data  Types"  in  Chapter  6. 

Examples: 

TYPE  LIBRARY  =  TITLE, AUTHOR , PUBL I SHER : 5TR I NGC 25 ] ; 
REFERENCE : INTEGER 
DIM  1QDKC500) : LIBRARY 

TYPE  PfiRTS  =  lTEM,LDeATTDNrSTRI«©C»]  5  GAT:REALj 

QUANTITY; INTEGER 

DIM   INVENTDRYCI 000):PARTS 

Sampla  PcogKam: 

This  procedure  builds  an  array  to  contain  a  book  reference  list, 
including  the  book  title,  the  author's  name,  the  publisher,  and  a 
reference  number.  It  does  so  by  using  TYPE  to  create  a  special 
data  structure  to  store  all  the  information  for  each  book. 

PROCEDURE  books 

nrrwE  l  i  brar y=t  i  tie  ,  a  uth  or  ,  puil  i  s wir  ?«Tf  hh^s  1 3  b  i  ? 

REFERENCE: INTEGER 

□DIM  BDDKSCI 00):LIBRARY 

OT=0 

QLDQP 

dT=T+1 

□  INPUT  "BOOK  TITLE.  . 
□BDDKS(T) .TITLE=BT$ 

□EXITIF  BOOKSCTJ.TITLE=""  THEN 

□GOTO  1 00 

□ENDEXIT 

□  INPUT  "Book  Author.  .  .■■,BA$ 
□BODKSCT) . AUTHQR=BA$ 

DIM  PUT  "Bo  ok  Publisher...", BP  $ 
□BDDKSfT) .PUBLISHER=BP$ 

□  INPUT  "Reference  Number  ..." ,BDOKSCT) . REFERENCE 

□ENDLDDP 

1 00OFOR  X=1    TO  T-1 

DPRIHT  BDOKStXJ. TITLE;  "  ,  ";  BOOIStSO . AUTHOR j  "  , 

■  I  ■ 

7 

□BOOKSCX). PUBLISHER;    "    ,    ";   BDDKSC X ). REFERENCE 

□NEXT  X 

□END 
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UNTIL  Terminates  a  REPE  J^  loop  on  specified 
condition 


^smtax:  REPEAT 

procedure  lines 
UNTIL  expression 

Function:  Ends  a  REPEAT  loop.  REPEAT  establishes  a  loop 

that  executes  the  encompassed  procedure  lines  until  the 
result  of  the  expression  following  UNTIL  is  true.  Because  the 
loop  is  tested  at  the  bottom,  the  lines  within  the  bop  are  ei^ 
cuted  at  least  once. 

Parameters: 

procedures       Statements  you  want  to  i^cute  in  the  loop. 

Urns 

expression        A  Boolean  expression  (the  result  must  be 
either  True  or  Ealse). 

Examples: 

REPEAT 

COUNT  =  COUKT+1 
UNTIL  COUNT  >  100 

INPUT  X,Y 
REPEAT 
X  =  X-1 

Y  =  Y-1 

UNTIL   X<1    OR  Y<0 

See  REPEAT  for  more  information. 
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USING  Formats  PRINT  output 


Syntax:    l*MDfr  \0^mM  tJMd  [jforoaig  iMdidaM,4 

Function:  Prints  data  using  a  format  you  specify.  This  state- 
ment is  especially  useful  for  printing  report  headings, 
accounting  reports,  checks,  or  any  document  req'ulrlni  a  spe- 
cific format. 

USING  is  actually  an  extension  of  the  PRINT  statement.  The 
same  rules  that  apply  to  the  PRINT  statement  also  apply  to 
the  PRINT  USING  statement  (see  PRINT). 

Parameters: 

path  The  number  to  an  opened  device  or  file.  If  you 

do  not  specify  path  the  default  is  #1,  the  video 
screen  (standard  output  device).  To  print  to 
another  device  or  file,  first  OPEN  a  path  to 
that  file  or  device  (see  OPEN). 

format  An  expression  specifying  the  arrangement  of 

the  displayed  data. 

data  Any  numeric  or  string  constant  or  variable. 

Always  enclose  string  constants  within  quota- 
tion marks.  Separate  all  data  items  with 
semicolons  or  commas. 

See  PRINT  USING  for  more  information. 
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Converts  string  data  to  numeric  data 


Syntax:  \AL,{string) 

Function:  Converts  string-type  data  to  num@^-^^e.  WlL  is 
the  inverse  of  the  STR$  function.  It  returns  the  real  value 
represented  by  the  characters  in  a  string.  If  any  character  in 
the  specified  string  is  not  numeric,  BASIC09  returns  an  error. 

Parameters: 

string  An  ASCII  string  containing  one  or  more  of  the 

following  characters:  0123456789.  +  $-. 

Examples: 

PRINT  VAL(123) 

ftt='M4.e©» 

PRINT  VflLtA$5 
Sample  Program: 

This  procedure  calculates  an  exponential  value,  then  adds  the 
necessary  number  of  zeroes  to  convert  it  to  standard  notation.  It 
uses  STR$  to  convert  the  original  number  to  a  string,  then  uses 
YAL  to  convert  the  exponent  into  a  value  to  determine  the  cor- 
rect decimal  place. 

PRDCEDURE  biftium 

□DIM  C, PLACES, B,S1GN:STR1NG;  EX , GDUNT , NEWCDUNT , 
DECIMAL : INTEGER 

CDIM  N EW.ZERD, NEWEST :STR I NG [ 1 B0] 

DCDUNT=-1 

□ZERO="0 0  00 0  00000000000 00000 0000 00000 2  00 000" 

DNEW=""  \NEWEST="" 

□INPUT    "What    number    do   you   want    to    raise    to  the 

power    of    14?. . .",NUM 

□A'NUM^I 4 

QB-STtt«A5 

□EX-SUBSTRC"E",B) 

□SIGN=MID«CB,EX+1 ,1 ) 
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nPLACES=RIGHT$(B,LEN(B)-EX-1 ) 

□FOR  T=1    TO  LENCB) 

Oe-MID*Ci,T,1> 

DIF  C="."  THEN 

□DECIMfiL=0 

DGOTD  1 0 

□ENDIF 

□DECIMAL=DECIMAL+1 
DIF  C="E"  THEN  100 

□NEW=NEN+C 
10CNEXT  T 

1 0  0DNEWCDUNT=VALC PL ACES) -DECIMAL 
□NEW=NEW+LEFT«CZERD,NEWCDUNT+1 ) 
OFOR  T=LENCNEN)  TD  1   STEP  -1 

0CaUNT=CDUNT+1 

DNENEST  =  MID$CNEW,T, 1  )  +  NEWEST 
DIF  MQDCCDUNT,3)=2  AND  T>1  THEN 
DNEWEST="'  ,"+NEWEST 
□ENDIF 
□NEXT  T 

□PRINT  MUW5  "  to  the  power  of  14  =  ";  A 

□PRINT  NEWEST 

□END 
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WHILE/DO/ENDWHILE  istmbiishes 

a  loop 


Syntax:     WHILE  expression  DO 
procedure  lines 
EI«)WHILE 


Function:  Establishes  a  loop  that  executes  Ae  encompassed 
procedure  lines  while  the  result  of  the  expression  following 
WHILE  is  true.  Because  the  loop  is  tested  at  the  t^,  the 
lines  within  the  loop  are  never  e^^cuted  unless  the  expression 
is  true. 

Parameters: 

repression       A  Boolean  expression  (has  a  result  of  True  or 

False). 

procedure  Program  lines  to  execute  if  the  expression  is 
lines  true. 


Examples: 

WHILE  COUNT  <   12  DO 

m\m  *  cDUNT+1 

ENDWHILE 


Sample  Program: 

'%a  must  emsbe  a  file  directory  names  umng  the  GET  sample 
program  before  you  can  use  the  following  procedure.  Copyutil 
uses  the  filenames  created  by  the  GET  sample  program  to  copy  a 
directory's  files  to  another  directory  you  specify.  You  must  spec- 
ify a  directory  name  that  does  not  exist.  Copyutil  uses  a 
WHILE/DO/ENDWHILE  loop  to  continue  copying  until  BASIC09 
reaches  the  end  of  the  file. 
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PROCEDURE  copyutil 

ODIM  PATH, T, COUNT: INTEGER;   F I LE , JOB , D I RNfiHEfSTRIN® 

□OPEN  #PATH,"dirf ile":READ 

DINPUT  "Name  of  new  d i r ec t ory . . . " , D I RN AME 

□IHILL  "M^^tUrp?  "*BIRNAME 

□SHELL  "LOAD  COPY" 

□WHILE  NGTCEDF<#PATH) )  DD 

OREAD  #PATH,FILE 

□JDB=FILE+"  "+DIRNAME+"/"+FILE 

□ON  ERROR  ©OTtJ  1 0 

□PRINT  "COPY  ";  JOB 

□SHELL  "COPY  "+JOB 

10DQN  ERROR 

□ENDWHILE 

□CLOSE  #PATH 

OEND 
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WRITE   Writes  data  to  a  sequential  file  ojr 
device 


Syntax:     WRITE  \.#path,]  data 

Function:  Writes  an  ASCII  record  to  a  sequential  file  or  to  a 
device. 

Parameters: 

path  A  variable  containing  the  path  number  of  the 

file  or  device  to  which  you  want  to  send  data. 
Path  can  be  one  of  the  the  standard  I/O  paths 
(0,  1,  2). 

data  The  data  you  want  to  send  'mm'  tlje  specified 

path. 

Notes: 

The  fdloipittf  information  deals  with  writing  sequ^ial  disk 
files: 

•  To  write  file  records,  you  must  first  dimension  a  variable  to 
contain  the  path  number  of  the  file,  then  use  OPEN  or 
CREATE  to  open  a  file  in  the  WRITE  or  UPDATE  access 
mode. 

•  Records  can  be  of  any  length  within  a  file. 

•  Individual  data  items  in  the  input  record  are  separated  by 
ASCII  null  characters,  "ffiu  can  also  separate  numeric  items 

with  comma  or  space  character  delimiters.  Each  input 
record  is  terminated  by  a  carriage  return  character. 

Examples: 

WRITE  #PATH,DATA$ 
WRITE  #1 ,RESPDNSE$ 
WRITE  #OUTPUT, INUEXCX) 
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□PEN  #PATH,"namef ile":WRITE 

FDR  T=1    TO  10 

READ  NAME$ 

WRITE  #PATH,  NAME* 

NEXT  T 
CLOSE  #PATH 

DATA  " J IM" , " JOE" , "SUE" , "TINA" , "WENDY" 

DATA  "SALL", "MICK  IE", "FRED", "MARV", "WINN  IE- 


Sample  Program: 

This  procedure  selects  100  random  values  between  1  and  10.  It 
uses  WRITE  to  place  the  values  into  a  disk  file,  Next,  it  reads 
values  from  the  file  and  uses  astmsks  to  ioAiitmH  h&w  tmaf 
times  RND  selected  each  value. 

PROCEDURE  randlist 

DDIM  SHDW,BUCKET:STRING 

□DIM  T,PATH,SELECTC10),R: INTE0ER 

DBUCKET""*  •  ••*•••••*••••»••••»*••'* 

□FOR  T=1  TO  10 
DSELECT(T)=0 
DNEXT  T 

□ON  ERROR  ©DTO  10 
□SHELL  "DEL  RANDFILE" 
1 0D  ON  ERROR 

□CREATE  #PATH  /'randf lie": UPDATE 

□FDR  T=1   TD  100 

□R=RNDt9>+1 

□WRITE  (CPATH.R 

□NEXT  T 

□PRINT  "Random  Distribution" 
□SEEK  #PATH,0 
□FDR  T=1   TO  1 00 

□READ  #PATH,NUM 
□SELECT(NUM)=SELECTCNUM)+1 
□NEXT  T 

□FDR  T=1   TD  10 

DStitJW-R  I  dWTi  CBtlGKET ,  SELEeTCT)  ) 

□PR  I  NT  USING  "S6< , 1 3  < , S2< , S20  < " , "Numbe  r " , T , " : " , 
SHOW 
□NEXT  T 
□CLOSE  #PATH 

mm 
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XOR   Returns  the  exclusive  OR  of  two  values 


Syntax:     operandi  XOR  operand2 


Function:  Performs  the  logical  exclusive  OR  operation  on  two 
or  more  values,  returning  a  value  of  either  TRUE  or  lALSE. 

Parameters: 

operandi  Boolean  values  or  expressions  (that  result  in 

operands        values  of  True  or  Ealse). 

Examples: 

PRINT  A>2   XOR  B>3 

PRINT  A$="YES"   XOR  B$="YES" 

Sample  Program: 

This  procedure  lets  two  people  type  numbers  until  one  of  them 
guesses  the  number  that  the  computer  picks.  It  uses  XOR  to 
dBt&ms&m  litoit  one  of  the  numbers  tfpei  is  the  correct  number, 
but  not  both. 

PROCEDURE  drawstraw 

□DIM  NUM1  ,NUM2,R:  INTEGER;  A:BDDLEAN 

UPRINT  "This   program  will    help  you  pick" 

□PRINT  "between  two  people.   Choose  who  will  be" 

□PRINT  "Person  1  and  who  will  be  Person  2." 

□PRINT  "Then,   enter  numbers  between  1   and  10" 

□PRINT  "when  requested." 

□PRINT 

□R  =  RNDC1  0) 

10OIHPUT  "Person  1,   type  a  number  and  press 
ENTER. . .",NUM1 

□INPUT  "Person   2,    type  a  number  and  press 
ENTER .  .  . "  ,NUM2 
□A=NUM1=R  XOR  NUM2=R 
□IF  A-FALSE  TMEH 

□PRINT  "You'll  have  to  try  again..." 
□PRINT 
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□GDTD   1 0 
DENDIF 

□IF  NUM1=R  THEN 

OPRINT  "You  win.  Person  1" 

DENDIF 

DIF  NUM2=R  THEN 

□PRINT  "You  win,   Person  2" 

□END  IF 

□PRINT  "The  Number  was.,,";  R 

□END 
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Program  Optimization 


BASICOD's  multipass  compiler  produces  a  compressed  and  optim- 
ized low-level  I-code  for  execution.  Compared  to  other  BASIC  lan- 
guages, BASIC09  greatly  decreases  both  the  storage  space 
required  for  program  code  and  the  execution  speed  of  programs. 

Because  BASIC09  produces  I-code  at  a  powerful  level,  it  can 
handle  numerous  MPU  (micro  processor  unit)  instructions  with  a 
single  interpretation.  Therefore,  fer  coinplex  programs,  there  is 
little  performance  difference  between  the  execution  of  I-code  and 
pure  machine-language  instructions. 

Most  BASIC  languages  have  to  compile  from  text  as  they  run,  or 
search  tables  of  tokens  in  order  to  execute  code.  Instead, 
BASIC  09  I-code  instructions  contain  direct  references  to  vari- 
aMes,  stat^eiifs,  and  labels.  BASIC09  fully  utilizes  the  power  of 
the  6809  instruction  set,  as  well,  which  is  optimized  for  efficient 
execution  of  compiler-produced  code. 

Because  BASIC09  interprets  I-code,  you  have  a  variety  of  entry- 
time  and  run-time  tests  and  development  aids.  The  editor  reports 
syntax  errors  immediately  when  they  are  entered.  The  debugger 
lets  you  debug  using  original  program  source  statements  and 
names.  The  I-code  interpreter  performs  run-time  error  checking 
of  array  structures  and  BASIC09  functions. 

Optimum  Use  of  Numeric  Data  Types 

The  following  notes  apply  to  the  use  of  BASIC09  numeric  data 
types: 

•  BASIC09  includes  several  different  numeric  representa- 
tions (real,  integer,  byte),  and  performs  automatic  type 
conversions  between  them.  This  means  that  without 
care,  your  code  might  contain  expressions  or  loops  that 
take  more  than  ten  times  longer  to  execute  than  is 
necessary. 
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•  Some  BASIC09  numeric  operators,  such  as  +  and  /, 
and  some  BASIC09  control  structures  include  versions  for 
both  real  and  integer  values.  Integer  versions  execute 
much  faster  and  can  have  slightly  different  properties. 
Feat  instance,  integer  division  discards  any  remainder. 

Integer  operations  are  faster  because  they  use  corre- 
sponding 6809  instructions.  Using  integers  increases 
speed  and  decreases  storage  requirements.  Integer  opera- 
tions use  the  same  symbols  as  real  operations,  but 
BASIC09  automatically  selects  the  integer  operations 
when  when  all  operands  of  an  expression  are  of  byte  or 
integer  tj^pe. 

•  Type  conversion  takes  time.  Using  expressions  with  oper- 
ands and  operators  of  the  same  kind  is  most  efficient. 

•  BASIC09's  real  (floating  point)  math  provides  excellent 
performance.  It  includes  a  40-bit  binary  floating  point 
representation  and  uses  the  CORDIC  technique  to  derive 
all  traftseettdental  functions.  This  integer  ^ifb-and-add 
technique  is  faster  and  more  consistent  than  the  common 
series-expansion  approximations. 

•  At  times,  you  can  obtain  similar  or  identical  results  in  a 
number  of  different  ways  and  at  different  execution 
speeds.  For  example,  if  the  variable  Value  is  an  integer, 
then  Va  lue»2  is  a  fast  integer  operation.  However,  if  the 
expression  is  Value»2.0,  2.0  is  represented  as  a  real 
number  and  the  operation  requires  real  multiplication. 
BASIC09  must  transform  the  integer  Value  iillo  a  real 
value.  If  the  result  of  the  expression  is  assigned  to  an 
integer  type  variable,  BASIC09  must  transform  the 
result  back  to  an  integer  type.  The  decimal  point  can 
slow  the  operation  by  about  ten  times. 
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Arithmetic  Functions  Ranked  by  Speed 


Referring  to  the  previous  table  can  help  you  in  your  program- 
ming. For  instance,  notice  that  it  is  quicker  to  add  a  value  to 
itself  rather  than  multiplying  it  by  2.  Similarly,  multiplying  a 
value  by  itself  or  using  SQ  on  a  value  is  much  faster  than  rais- 
ing a  value  to  the  power  of  2. 

Notice  that  a  real  divide  takes  3870  cycles,  while  a  real  multipli- 
cation takes  only  990  cycles.  Multiplying  a  value  by  0.5  is  four 
times  quicker  than  dividing  the  value  2, 

Quicker  Loops 

BASIC09  has  two  versions  of  FOR/NEXT  loops,  one  for  integer 
loop  counter  variables  and  one  for  real  loop  counter  variables.  It 
aaitSffiiaMeally  uses  the  appropriate  version.  Integer  FOR/NEXT 
loops  are  much  faster  than  real  FOR/NEXT  loops. 

Other  kinds  of  loops  also  run  faster  if  you  use  integer  type  vari- 
ables fbr  the  loop  counters.  When  writing  program  loops,  remem- 
ber that  statements  inside  the  loop  can  execute  many  times  for 
each  execution  outside  the  loop.  Whenever  possible,  compute  val- 
ues before  entering  loops. 


Operation 


Typical  Speed 
in  MPU  Cycles 


Integer  add  or  subtract 

Integer  multiply 

Real  add 

Real  subtract 

Integer  divide 

Real  multiply 

Real  divide 

Real  square  root 

Real  logarithm  or  exponential 

Real  sine  or  cosine 

Real  power 


20400 
32500 
39200 


150 
240 
440 
540 
960 
990 
3870 
7360 
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Arrays  and  Data  Structures 

The  internal  workings  of  BASIC  09  use  integer  numbers  to  index 
arrays  and  complex  data  structures.  This  means  that  BASIC09 
must  convert  real  type  vaifaMe  w  esp-esslm  snbsertpte  be&r©  it 
can  handle  them.  Using  integer  expressions  for  subscripts 

increases  execution  speed. 

Using  the  assignment  statement  LET  to  copy  identically  sized 
data  structures  is  much  faster  than  copsring  arrays  or  structures 
dement-by-element  inside  a  loop. 

The  PACK  Command 

PACK  causes  a  second  compilation  of  a  specified  procedure. 
Depending  on  such  variables  as  the  number  of  procedure  com- 
ments and  the  inclusion  of  line  numbers,  packed  procedures  exe- 
cute firom  10  t&  30  percent  &ster.  Line  numbers  cause  tuop^ted 
procedures  to  run  slower. 

Minimizing  Constant  Expressions 
and  Bubexpressions 

Pbr  maximum  execution  speed,  precalculate  constant  expres- 
sions. For  instance,  x  =  x  +  5  produces  the  same  result  as  x  = 
x  +  5qrt(l00)/2.  However,  the  first  expression  requires  approxi- 
mately 150  MPU  cycles  viMi&  the  secMid  ©cpression  requires 
11,650  MPU  cycles.  If  you  use  such  an  expression  inside  a  loop, 
the  additional  execution  time  is  enormous. 

Input  and  Output 

Accessing  data  one  line  or  record  at  a  time  is  much  faster  than 
accessing  it  one  character  at  a  time.  Also,  the  GET  and  PUT 
statements  are  much  faster  than  READ  and  WRITE  statements 
when  accessing  disk  files.  This  is  because  GET  and  PUT  use  the 
same  binary  format  as  BASIC09's  internal  operations.  READ, 
WRITE,  PRINT,  and  INPUT  must  perform  binary-to-ASCH  or 
ASCII-to-binary  conversions,  which  take  more  time. 
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Error  Codes 


Signal  Errors 

Code  Meaning 


1  Ulaeondittenal  t^mination 

2  Keyboard  termination 

3  Keyboard  interrupt 


BASIC09  Error  Codes 

IQ&4b  Meaning  


10 

T  In vpfocn  i  7pH  ^vmHfil 

12 

Tl If^crn  1  cfn "f" ATTiPTii"  f^riTi cil'Tiiptinn 

11 

.-JL& 

T-pnr]p  nvPvFlnw  uppH  mriTP  wnvV^TiaPiC*.  t*it(P5^^ 

J.ilcrgcll  l^llCllllid  ICXdOIIUCj   UdU.  JJdUlX  XUUXXMCSl  ^•^v 

Mi 

TllpD"?!]  mnrip  ('vpfiH/wTit'p/nnHiii'pl  -  f?iTAf*-fnTV  nnl 

XilC^gCtl   lliULlC    VX  CcXU/  VV  1  luC/ LiLJUclLC^        UJLAC?vuUX  jr  UXXJ 

1f$ 

liiCgdl  XXU-lXiUcX 

lix6g£Li  prBIlX 

18 

Tllpo"fil  OTiPTflnn 

XllCgClX   L/Lfd  dXXU 

19 

Illegal  operator 

20 

Illegal  record  field  name 

21 

Illegal  dimension 

22 

Illegal  litra-al 

23 

Illegal  relational 

24 

Illegal  type  suffix 

25 

Too-large  dimension 

26 

Too-large  line  number 

2f 

Missing  assignment  statement 

28 

Missing  path  number 

29 

Missing  comma 

30 

Missing  dimension 

31 

Missing  DO  statement 

32 

Memory  full,  need  more  \«t)i^l^ae@  fflteffiory 

33 

Missing  GOTO 

34 

Missing  left  parenthesis 

35 

Missing  line  fiference 

36 

Missing  operand 

37 

Missing  right  parentfeesfs 

38 

Missing  THEN  statemrait 

39 

Missing  TO 

B^ICM  Qmmmands  B^isreme 


Code  Meaning 


Missing  variable  reference 

41 

XT             J  '  J. 

No  ending  quote 

42 

Too  many  subscripts 

43 

T  T    1      „  J 

Unknown  procedure 

A  A 

44 

Multiply-defined  procedure 

45 

Divide  by  zero 

AO 

4b 

Operand  type  mismatch 

An 
47 

String  stack  overflow 

48 

Unimplemented  routine 

49 

Undefined  variable 

50 

Floating  ovesrflow 

51 

Line  with  compiler  error 

CO 

52 

Value  out  of  range  for  destination 

5o 

Subroutine  stack  overflow 

04 

Subroutine  stgusk  underflow 

55 

Subscsript  out  of  range 

Ob 

Parameter  error 

a/ 

System  stack  overflow 

do 

I/O  type  tnisinatch 

59 

I/O  numeeie  input  format  bad 

60 

I/O  conversion:  number  out  of  fange 

61 

Illegal  input  format 

bz 

I/O  format  repeat  error 

bo 

I/O  format  syntax  error 

64 

Illegal  path  number 

65 

Wrong  number  of  subscripts 

66 

Non-record-type  operand 

67 

Til            1  J. 

Illegal  argument 

68 

Illegal  control  structure 

69 

Unmatched  control  structure 

70 

Illegal  FOR  variable 

71 

Illegal  expression  type 

72 

Illegal  declarative  statement 

73 

Array  size  overflow 

74 

Undefined  line  number 

75 

Multiply-defined  line  number 

76 

Multiply-defined  variable 

77 

Illegal  input  variable 

78 

Se^0utcf  range 

79 

Missing  data  stat^nent 

Error  Codes  I A 


Windowing  and  System  Errors 

Code  Miming  


183  Illegal  window  type 

184  Window  already  defined 

185  Font  not  found 

186  Stack  overflow 

187  Illegal  argument 

188  {Hmsed) 

189  Illegal  coordinates 

190  Internal  integrity  check 

191  Buffer  size  is  too  small 

192  Illegal  command 

193  Screen  or  window  table  is  full 

194  Bad/undefined  buffer  number 

195  Illegal  window  definition 

196  Window  undefined 

197  (unused) 

198  (unused) 

199  (unused) 

200  Path  table  full 

201  Illegal  path  number 

202  Interrupt  polling  table  full 

203  Illegal  mode 

204  Device  table  full 

205  Illegal  module  header 

206  Module  directory  full 

207  Memory  full 

208  Illegal  service  request 

209  Module  busy 

210  Boundary  error 

211  Bnd  affile 

212  Returning  non-allocated  memory 

213  Non-existing  segment 

214  No  permission 

215  Bad  path  name 

216  Path  name  not  found 

217  Segment  list  full 

218  File  already  exists 

219  Illegal  block  address 

220  Phone  hangup  data  carrier  detect  lost 

221  Module  not  fbond 
223  Suicide  attempt 
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224  Illegal  process  number 

226  No  children,  can't  wait  for  nonexistent  child  process 

227  Illegal  SWI  code 

2^8  Procesi  aborted,  sigoal  2 

229  Process  table  full,  can't  tek  a  process 

230  Illegal  parameter  area 

231  Known  module 

^  Incorrect  module  CRC 

233  Signal  error 

234  Non-existent  module 

235  Bad  name 

237  System  RAM  full 

TJnknown  jTOcess  ID 

239  No  task  number  available 

240  Illegal  unit  error 

241  Bad  sector  number 

242  Write  protected  disk 

243  CRO  error 

244  Read  error 

245  Write  error 

246  Not  ready,  device  not  ready 

247  Seek  error 
2^  Media  full 

249  Wrong  type,  incompatible  media  type 

250  Device  busy 

251  Disk  ID  change,  disk  changed  with  opea  files 

252  Record  is  locked  out 

253  Non-sharable  file  busy 
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The  Inkey  Program 


An  assembled  version  of  Inkey  is  included  on  the  CONFIG/ 
BASIC09  diskette.  Use  Inkey  from  BASICQ9  with  the  RUN 
statement. 


'  INKEY  -  a  subroutine  for  BfiSIWS  by  Robert  Doggett 

* 

•  CallBd  byi  IM  IWmpVirt 

RUN  INKEVCPath.StrVar) 

♦  INKEY  determines  if  a  ley  has  been  typed  on  the  given  path 

*  (Standard  Input  if  not  specified),  and  if  so,  returns  the  next 

•  character  in  the  String  Variable..  If  ii,o  key  has  been  typed,  the 


»  null  firing  is  fetitriifi.  If 

a  path  it  specified, 

it  nust  be 

•  either  type  BYTE 

or  INTEGER, 

m 

INKEV 

IFP1 

USE 

/De/DEFS/DS9D£FS 

ENDC 

tm 

TYPE 

set 

SBRTN*DBJCT 

REVS 

set 

REENTt! 

tm  mmsi 

mod 

InKeyEnd.InKeyNam.TYPE.REVS 

.InKeyEnt, SIZE  ' 

M8D  49GEGBG5 

InKeyNam 

fcs 

"Inkey" 

D  yiEl 

org 

a 

Parameters 

D  im 

Return 

rmb 

2 

Return  addr  of  caller 

D  tm 

PGount 

rmb 

? 

Num  of  params  following 

D 

Paraml 

rmb 

2 

1 st  param  addr 

D  mB 

Lengthi 

rmb 

2 

size 

D  tM% 

PartuI 

nil' 

I 

2nd  param  addr 

D  t»k 

Length? 

rmfr 

2 

size 

mc 

EtParam 

equ 

$38 

mi 

SIZE 

equ 

» 

3064 

InKeyEnt 

leax 

Paraml ,S 

B-l 
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Hf4 

tm 

Idd 

Pcountjf 

let  parameter  court 

1  0830M1 

cmpd 

#1 

just  one  parameter? 

im 

2727 

beq 

lnKey20 

,  .Yes;  default  path  fl=0 

108300J2 

cmpd 

n 

Are  there  two  parains? 

2635 

bne 

ParamErr 

No,  abort 

ECF804 

Idd 

[Parain1,S! 

Get  path  number 

AEGG 

Idx 

Lengthl  ,S 

mi 

301F 

leax 

-1  ,x 

byte  variable? 

mi 

270G 

beq 

IiiKey10 

,  .Yes;  (fl)=Path  nuntber 

m% 

301F 

leax 

-l.X 

Integer? 

2628 

btie 

ParamErr 

..NiJi  abort 

1F98 

tfr 

B,fl 

0331 

30G8 

lnKey10 

leax 

Param2,S 

0033 

EE02 

Idii 

2,)( 

length  of  string 

0035 

flE84 

Idx 

i,l 

addr  of  string 

0037 

C6FF 

Idb 

«FF 

0039 

E7e4 

5tb 

0,1( 

Initialize  to  null  str 

003B 

11830002 

cmpu 

#2 

at  least  two-byte  str? 

im 

2S«2 

Um 

lTiKey3« 

0B4i 

E701 

5tb 

1,X 

put  str  terminator 

0043 

C601 

lnKey30 

Idb 

#55. Ready 

0045 

103F8D 

DS9 

UGetStt 

is  there  any  data  ready? 

0048 

2508 

bcs 

InKey90 

..Ng;  exit 

IPS 

1% 

#t 

004E 

103F89 

m 

riRead 

Read  one  byte 

0051 

39 

rts 

returns  error  status 

0052 

CIFG 

InKey^B 

cmpb 

*E$NotRdy 

0054 

2603 

bne 

InKeyErr 

im 

39 

rts 

(carry  clear) 

0057 

C638 

ParamErr 

Idb 

iEIParam 

Parameter  Error 

0059 

43 

InKeyErr 

coma 

005A 

39 

rts 

005B 

lflG316 

emod 

M5E 

InKeyErd 

equ 

« 
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Index 


ABS  eommand  U-4 
absolute  value  11-4 
accessing 

files    8-1,  10-8 

lines  (editor)   4-4  -  4-5 

OS-9  conwiiands  from 
BASIC  3-7 
ACS  command  11-5 
adding  lines   4-10  -  4-12 
addition   7-3  -  7-4 
ABDR  command  11-6 
address 

of  variable    6-8,  11-6 

space  11-6 
advantages  of  BASICG9  1-1- 
1-2 

ALPHA  (medium-res)  9-9, 

9-13 
alphanumeric 

mode  9-10 

screen   9-9,  9-13,  9-30 
ALT  key    1-6,  9-4 
AND 

command  11-8 

logical  AND 

command  11-84 

operator   7-3,  7-4,  7-7 
appending 

data  to  files  8-3 

strings  7-6 
ARC  command  (high-res) 

9-50 
arccosine  11-5 
arcsine  11-10 
arctangent  11-11 
arithmetic 

function  speed  12-2 

(^^ators  7-3 
array  6-9  -  6-13 

address  11-6 

element  6-9 

index  11-12 

with  random  access 
files  8-9 


ASC  command  11-9 
ASCII 

character  value  11-18 
codes    9-1  -  9-6,  11-9 
ASN  command  11-10 

variable  storage  11-31 
variable  values  11-78 
variables  (debug)  5-3 

ATN  command  11-11 

auto  eseeuMon  3-8 

automatic  earrar  checking  1-4 

background  color 

high-resolution  9-34 
medium-resolution  9-11 
backslash  1-6 
BAR  command  (high-res) 

9-52  -  9-53 
base  10  logarithm  11-83 
BASE  command    11-12  - 

11-13 
BASIC09 

advantages  1-1-1-2 
graphics  with  128K 

9-37  -  9-39 
quitting    1-5,  3-1 
starting   1-2  -  1-4 
staftittg  wiBitora 
from   9-39  -  9-41 
beep  9-54 
beginning  debug  5-1 
BELL  command  (high-res) 
9-54 

binary  data  record  11-58 

BLNKOFF  command  (high- 
res)  9-55 

BLNKON  command  (high- 
res)  9-55 

BOLDSW  command  (high- 
res)  9-56 
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Boolean 

data   6-1  -  6-2,  6-5 
functions  7-10 
OR  11-106 

TRUE    11-175  -  11-176 
value  11-51 
bcrto  color  (Mfli-res)  9-58, 
9-65 

BORDER  command  (high- 
res)  9-58 

BOX  command  9-60-9-61 

brace  characters  1-6 

BREAK 

command  (debug)  5-2 
key   1-6,  5-2 

br^^Lpoint  (debug)  5-2 

bujfc 

defining  9-78 
font  (high-res)  9-94 
get/put  (high-res)  9-117 
group  (high-res)  9-101 
pattern  (high-res)  9411 

button,  joystick  (medium- 
res)    9-9,  9-22 

BYE  command   1-5,  3-1,  10-9, 
11-14 

byte 

data  type    6-1  -  6-2 
numeric  range  6-2 
retrieml  fcom  a  file  8-5 
type  functions  7-9 

calculate 

low»-res  characters  9-5 
sine  11-1S4 
square  root  11-158 

call  a  shell  command  10-9 

carriage  return  1-7 

high-resolution  9-67 

CHAIJ?  eOifxmmai.   11-15  - 
11-16 

changing 

a  procedure  name  10-9 
color  (high-res)    9-65  - 
9-66 


changing  {cont'd) 

color  (medium-res)  9-9 
directory   3-1,  3-7,  10-9, 

11-17,  11-19 
file  pointer  11-148 
procedures  1-4 
scale  (Mgh-res)   9-121  - 

9-122 
text   4-7  -  4-9 
text  (editor)    4-1  -  4-2 
working  area  (high-res) 

9-76 
character 

backslash  1-6 
blink  (high-res)  9-55 
braces  1-6 
brackets  1-6 
fonts  9-43-9-44 
graphic  1-6 

high-resolution   9-8,  9-94 
reverse  video  (high- 
res)  9-120 
tilde  1-6 

underline  (high-res) 

9-126 
underscore  1-6 
up  arrow  1-6 
value  11-18 
vertical  bar  1-6 
fflU  command  3-1,3-?, 

10-9,  11-17,  11-19 
CHX  command   3-1,  3-7, 

10-9,  11-17  -  11-19 
CIRCLE 

Mfh-resolutSon  i-61 
medium-resolution  9-9, 
9-15  -  9-16 

CLEAR 

high-resolution  9-64 
k#  1-6 

medium  resolution  9-9, 
9-17 

close  a  window  (high-res) 
9-83  -  9-84 


Index 


CLOSE  conunand   11-20  - 

11-21 
code 

ASCII    9-1  -  9-6,  11-9 
error    11-43,  Al  -  A4 
COLOR 

high-resolution  §-65 

medium  resolution  9-9, 
9-18,  9-19 

color 

codes  (medium-res) 
9-10  -  9-11 

drfault  9-79 
high-resolution  9-31, 

9-109  -  9-110 
medium-resolution  9-11 
of  border  (high-res) 

9-58  -  9-59 
of  pixel  (medium-res) 

9-28  -  9-29 
of  screen  (medium- 
res)  9-26 
palette  default  9-79 
set  (medium-res)   9-18  - 
9-19 
command 

interpreter  3-1 
line  storage  area  3-3 
line  ssmabols  11-2 
lines  using  spaces  2-2 
mode  1-3 

mode  reference  10-9 
commands 

by  type  10-7 
configuring  (high-res) 

9-  47 
debug  10-11 
drawing  (high-res)  9-46 
editing  10-10 
executing  OS-9   3-7  -  3-8 
font  (high-res)  9-49 
quick  reference    10-1  - 

10-  6 
system  3-1 


commands  ^cont'd) 

text/bursor  (high-res) 

9-48 

using  wildcards  3-5 
window  (high-res)  9-45 
comments  in  a  procedure 

11-135  - 11-136 
compile  procedure   3-1,  3-8  - 

3-9,  10-9 
compiler,  multipass  12-1 
compiling 

procedures  1-5 
saving  space  1-2 
complement,  logical  11-96 
complex 

data  structure  1-2, 
8-11  -  8-12,  11-177  - 
11-178 
data  types    6-1,  6-13  - 
6-16 

compressed  procedures  12-1 
concatenation  7-3 
condensed  procedures  3-1 
configuring  commands  (high- 
res)  9-47 
constant  expressions  12-4 
constants,  string  6-7 
control  key  1-6 
converting 

data  types    6-6,  7-2 
numeric  types  11-54, 

11-71,  11-162  -  11-163 
string  data    11-181  - 
11-183 

copying  structure  elements 
6-16 

COS  command  11-22 
cosine  11-22 
create 

data  types  11-177 
overlay  windows  (high- 
res)  9-107 
procedures  2-1 
random  access  files   8-6  - 
8-9 
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create  (cont'd) 

sentences  procedure  4-3 
sequential  files  8-2  -  8-3 
windows  d-W5  -  9-&6 

CREATE  command    8-2  -  8-3, 

8-  6  -  8-7,  11-23  -  11-24 
CRRTN  command  (high- 
res)  9-67 

CTRL        1-6  - 1-7 

CTRL-BREAK  key 
sequence    1-6,  3-1 

CURDWN  command  (high- 
res)  9-68 

CURHOME  command  9/6f 

CURLFT  command  (high- 
res)  9-70 

CUROFF  command  (high- 
res)  9-71 

CURON  command  (high- 
res)  9-72 

current  command  line  1-7 

CURMIT  «Branara4  0ngh- 
res)  9-73 

cursor 

graphics  (high-res)  9-95, 

9-119 
graphics  (medium- 
res)  9-27 
invisible  (high-res)  9-71 
movement  1-6,  9-67  - 

9-68,  9-74  -  9-75 
position  11-116 
CURUP  command  (high- 
res)  9-74 
CURXY  command  Qiigh- 

res)  9-75 
CVCVREA  command  (high-rei) 

9-  76  -  9-77 

data 

changing  in  sequential 

file  8-4 
complex  types  6-1, 

6-13  -  6-16 
constants   6-6  -  6-7 


data  (cont'd) 

directory  3-7 
items  6-1 

manipulation   7-1  -  7-2 

meaning  6-1 
pointer  11-140 
reading    11-132  -  11-133 
structure   1-2,  11-177  - 

11-178,  12-2 
structure  address  11-6 
to  files  8-1 
type,  Boolean  6-5 
type,  byte  6-2 
type,  conversion  7-2 
type,  integer  6-3 
type,  real   6-3  -  6-4 
types   6-1,  10-8,  11-177  - 

11-178,  12-1 
types,  creating    11-177  - 

11-178 
DATA  command   11-25  - 
11-26 

DATE$  command   11-27  - 

11-28 
day  11-27 
deallocate 

Mmr  (high-res)  9-101  - 
9-102 

graphics  memory  9-30 
windows  (high-res) 

9-  83  -  9-84 

debug 

beginning  5-1 
breakpoint  5-2 
commands    5-2  -  5-4, 

10-  11 

display  procedure  5-3 

quitting  5-3 

starting   5-1,  5-4  -  5-5, 

11-  112 
tracing  5-4 

debug  command 
$  5-2 

BREAK  5-2 
CONT  5-2 


Index 


debug  command  {cmtdti 

DEG  5-2 

DIR  5-3 

LET  5-3 

LIST  5-3 

PRINT  5  -3 

Q  5-3 

RAD  5-2 

STATE  5-3 

STEP  5-4 

TROFF  8-4 

TRON  5-4 
default  colors  9-79 
DEFBUFF  command  (high- 
res)  9-78 
DEFCOL  command  (high- 
res)  9-79 
define  a  window  (high-res) 

§-86  -  9-87 
defining  string  variables  6-4 
DEG  command  11-29 
degrees,  selecting  in  debug 

5-2,  11-29 
DELETE  command  11-30 
delete  line    1-6,  2-2 

editor  4-2 

high-resolution  9-80, 
9-92 

deleting 

procedure  lines   4-6  -  4-7 

procedures  3-6 
delimiter  4-8 

in  sequential  files  8-2 

s3mibols  (editor)  4'-8 
DELLIN  command  (high- 
res)  9-80 
device  pith  11-104 
DIM  command   11-31  - 11-32 
DIM  statement   6-2,  11-31 

Dm 

command   3-1  -3-2,  10-9 
debug  i'S 
file  access  8-1 


directory 

change    3-1,  3-7,  11-17, 

11-19 
data  3-7 
esecution  3-7 
ROOT  3-7 
disassembled  procedtire  3-3 
disk  file  8-1 

creation  11-23 
deletion  11-30 
display 

a  formatted  listing  10-9 
a  window    1-6,  (high- 
res)    9-123  -  9-124 
clearing  (medium- 
res)  9-17 
current  command 

line  1-7 
last  line  1-7 
previous  window  1-6 
procedure  3-1 
procedure  from  debug 

5-3 
procedure 

information    3-1,  10-9 
text    11-119  -  11-120 
workspace  size   3-1,  10-9 
division  7-3 

remainder  11-93 
DO  command  11-34 
dot,  graphics  (medium-res) 

9-28  -  9-29 
draw 

a  circle  (high-res)    9-62  - 
9-63 

a  circle  (medium-res) 

9-9,  9-15  -  9-16 
a  line  (high-res)   9-103  - 

9-104 

an  ellipse  9-88  -  9-89 
arcs  (high-res)   9-50  - 

mi 

command  (high-res) 
9-46,  9-81  -  9-82 
pointer  (high-res)  9-125 
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draw  {cont'd) 

pointer  (medium-res) 
9-12 

lines  (medium-res) 

9-24  -  9-25,  9-103 
rectangles  (high-res) 
9-52  -  9-53,  9-60  -  9-61 
DWEND  command  (high- 
res)    9-83  -  9-84 
DWPROTSW  command  (high- 
res)  9-85 
DWSET  command  (high- 
res)    9-86  -  9-87 

edit 

compiler  3-1 

mode,  entering  1-4 

pointer  4-1 

terminating  2-3 
EDIT  command   3-1,  10-9  - 

10-10 
editor   4-1  -  4-9 
element  6-9 
elements 

of  a  structure* 
copying  6-16 

of  an  array  6-9 
ELLIPSE  command  (high- 
res)    9-88  -  9-89 
ELSE  command  11-35 
END  command    11-36  -  11-37 
end  execution  11-14 
end-of-file 

RiBSSage  1-6 

test  11-42 
ENDEXIT  command  11-38 
ENDIF  command  11-39 
ENDLOOP  command  11-40 
ENDWHILE  11-41 
ENTER 

command  (editor)  4-1 

in  the  editor  4-4 

key  1-7 


entering 

debug   5-4  -  5-5 
the  edit  mode  1-4 

EOF  command  11-42 

equal  operator  7-5 

erase 

a  disk  file  11-30 
procedures    3-1,  11-72 
to  end  of  line  9-90 
to  end  of  window  9-91 
EREOLINE  comtttaM  (Mgh- 

res)  9-90 
EREOWNDW  command  (high- 
res)  9-91 
ERLINE  command  (high- 
res)  9-it 
ERR  command   11-43  - 11-44 
error 

checking,  automatic  1-4 
code   11-43  -  11-44, 

A-1  -  A-4 
in  a  program  line  2-2 
simulation    11-45  -  11-46 
trapping   11-97  -  11-99 
ERROR  command  11-45 
escape  function  1-6 
establishing  a  window  9-32, 

9-41,  9-86-9-87 
evaluating  expressions   7-1  - 
7-2 

evaluation,  order  of 

operators   7-4  -  7-5 
examine 

a  procedure  4-4 
memory  11-113 
exclusive  OR    11-187  -  11-188 
EXEC  file  access  8-1 
executable  procedures  3-8 
execute 

a  procedure   2-3,  3-1, 
3-8,  10-9, 
11-145  -  11-147 
an  OS-9  command  3-1, 
3-7  -  3-8 
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Index 


execute  (cont'd) 

modules    11-15  -  11-16 

procedure  lines  11-34 
execution 

automatic  3-8  -  3-9 

directory  change  3-1, 
3-7 

speed  1-1 

stepping   5-5  -  5-6 

stopping  11-161 

termination  11-14 
EXITIF/THEN/ENDEXIT 

commands  11-47 
exiting 

BASIC09  1-5 

debug  5-3 
EXP  command  11-50 
exponent,  natural  11-50 
exponentiation  7-3 
expression  7-1 

FALSE 

command   11-51  - 11-52 

value  7-7 
faster  loops  12-2 
file 

listing  procedxires  to  3-4 
path  11-104 
pointer    8-3,  8-5, 

11-148  -  11-149 
pointer,  rewinding  8-11 
retrieving  bytes  8-5 
writing   11-129  - 

11-  130,  11-185- 

11-186 
files  8-1 

accessing   8-1, 10-8 
appending  data  8-3 
closing    11-20  -  11-21 
creating  random 

access   8-6  -  8-9 
creating  sequential   8-2  - 

8-4 

creation    11-23  -  11-24 
opening    11-104  -  11-105 


files  {cont'd) 

random  access    8-5  - 

8-  11 
writing  to  8-3 

FILL  command  (high-res) 
9-93 

filled  rectangles  (high-res) 

9-52  -  9-53 
finding 

graphics  screen  (mediixm- 

res)  9-20-9-21 
lines  4-5 
fire  button  (medium-res)  9-22 
FIX  command  11-53 
FLOAT  command  11-54 
FONT  command  (high-res) 
9-94 

font-handling  commands  (high- 
res)  9-49 

fonts   9-43  -  9-44 

FOR/NEXT  loops  11-159- 
11-160 

FOR/NEXf/SffiP 

commands  11-65  - 11-57 

foreground  color 

high  resolution   9-65  - 

9-  66 

medium  rescflution  9-11, 
9-18  -  9-19 
fork  a  shell    11-152  -  11-153 

to  a  window  9-32 
format 

medium  resolution  9-10 

of  screen  (medium- 
res)  9-26 

of  windows  9-34 
formatted  procedure  3-1 
formairting 

display  screen  11-180 

screen  display    11-122  - 
11-127 
functions   7-7  -  7-10 

Boolean  type  7-10 

byte  type  7-9 

integer  type  7-9 
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functions  {cont'd) 
logical  7-10 
numeric  type    7-9,  10-7 
real  type  7-8 
string   7-10,  10-7 
trace  5-5  -  5-6 
transcendeantal  10-7 

GCOLR  (medium-res)  9-9 

GCSET  command  (high- 
res)  9-95 

GET  command   8-5,  11-58 
high-resolution  9-96 

GET/PUT  buffer  9-78 

high-resolution  9-101 

GET/PUT  commands  (high- 
res)  9-47 

global  symbol  (editor)  4-5 

GLOC  (medium-res)  9-9, 
9-20 

GOSUB/RETURN 

commands  11-61 
GPLOAD  command  (high- 
res)  9-98 
graphics 

characters  1-6 
cursor  (high-res)  9-95, 

9-119 
cursor  (mediiim-res) 

9-9,  9-27 
high-resolution   9-31  - 

9-126 
levels  9-1 

logic  functions  9-105 
low  resolution  0.4  -  t-S 
medium-resolution   9-8  - 

9-30 

memory  deallocate  9-30 
number  of  levels  1-2 
pattern  (high-res) 

9-111  -  9-112 
pointer  (high-res)  9-42 
screen  (medium-res) 

9-26 


graphics  (.confd) 

screen  location  (medium- 
res)   9-20  -  9-21 
window   9-35  -  9-36 
with  128K    9-37  -  9-40 
greater  than  7-3,  7-5 
grid  fiirmat  (inedium-rresi) 

9-10 
group 

buffer  (high-res)   9-101  - 

9-102 
number  9-78 

hardware  window   9-32  -  9-35 
high-resolution   9-31  -  9-126 
adapter  9-22 
characters  9-8 
colors   9-109  -  9-110 
quick  reference   9-44  - 

9-4& 
text  9-42 
hour  11-27 

I-Code   3-3,  12-1 
IF/THEN/ELSE  loop  11-35 

IF/THEN/ELSE/ENDIF 
commands    11-63  -  11-65 

image,  get  (high-res)  9-98 

immortal  shell  9-32 

initialize  a  disk  file   11-23  - 
11-24 

INIZ  command   9-32  -  9-33 
Inkey  program   B-1  -  B-2 
INPUT  command   8-5,  11-68  - 

11-70 
input/output  12-4 
insert 

a  line  (high-res)   9-99  - 

9-100 
text  (editor)  4-1 
INSLIN  command  (high- 
res)    9-99  -  9-100 
INT  command  11-71 
integer 

constants  6^7 


Index 


integer  (cont'd) 

data  type   6-1,  6-2,  6-3 
functions  7-9 
numeric  range  6-2 
interfacing  with  OS-9  1-1 
invisible  cursor  (high-res) 

9-  71 

JOYSTK  9-9,9-22 
jump 

to  line  number   11-102  - 

11-103 
to  iultt^utuie   11-100  - 

11-101 

key 

ALT   1-6,  9-4 
BREAK  1-6,5-2 

CLEAR  1-6 

CTRL    1-6  -  1-7 

ENTER  1-7 
key  sequence 

CTRL  with  other 
keys    1-6  -  1-7 

SHIFT  with  other 
keys  1-6 
keyword  11-1 
KILL  command   3-1,  3-6, 

10-  9,  11-72  -  11-73 
KILLBUFF  command  (high- 
res)  9-101 

killing  a  procedure  3-6 

LAND  command   11-74  - 

11-  75 

language  modules  1-5 
last  line,  displaying  1-7 
left  brace  1-6 
left  bracket  1-6 
LEFT$  command  11-76 
LEN  command  11-77 
length  of  string  variables  6-4 
less  than    7-3  -  7-4,  7-5 


LET  command   6-8,  11-78  - 
11-79 

debug  5-3 
LINE  (medium-res)  9-9 
line 

accessing  (editor)  4-5 
adding   4-10  -  4-12 
adding  (editor)  4-10 
erasing  9-90 

see  also  line,  deleting 
inserting  (high-res) 

9-  99  -  9-100 
jumping  to   11-102  - 

11-103 
numbers  4-5 
renumbering   4-2,  4-10 
LINE  command 

hlgh-resolutioa  9-103 
medium-resoluttm  9-24 
line  deleting    1-6,  2-2,  9-92 
editor  4-2 
high-resolution  9-80 
in  procedures  4-6  -  4-7 
LIST  command  3-1,  3-2  -  3-5, 

4-6,  10-9 
listing 

procedures  3-2  -  3-5, 

6-6,  10-9 
procedure  lines 
(editor)  4-2 
to  a  fife  3-4 
to  a  printer  3-4 
LNOT  command    11-80  - 
11-81 

LOAD  command   3-1,  3-6, 

10-9 
loading 

a  buffer  (high-res)  9-98 
BASIC09    1-2  -  1-4 
procedures   3-1,  3-6, 

10-  9 

window  image  (high- 
res)    9-101  -  9-102 
local  variable  6-7 
LOG  command  11-82 
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LOGIO  command  11-83 
logarithm    11-82,  11-83 
logic  comparison  6-5 
LOGIC  conuxiand  (high- 
res)  9-105-9-106 
logical 

AND    11-8,  11-74  - 

11-75 
block  (file)  8-1 
complement  11-96 
functions  7-10 
NOT    11-80  -  11-81, 

li-m 

operators  7-7 
OR    11-87  -  11-88 
XDR  11-89-11-91 

loop 

EXITIF/ENDEXIT/ 
ENDEXIT  11-38, 
11-47  -  11-49 
FOR/NEXT  11-55, 
11-57,  11-95, 
ll-15f  - 11-160 
IF/THEN/ELSE/ENDIF 
11-35,  11-39, 
11-63  -  11-65 
LOOP/ENDLOOP 

11-40,  11-84  -  11-86 
REPEAT/UNTIL 
11-137  -  11-139, 
11-179 
WHILE/DO/ 

ENDWHILE  11-34, 
11-41,  11-183  -  11-184 
loop  repetition  11-95 
LOR  command    11-87  -  11-88 
low-resolution   9-1  -  9-7 
LXOR  command    11-89  - 
11-91 

math  1-2 

medium-resolution   9-8  -  9-30 

format    9-10  -  9-11 
MEM  command   1-3  -  1-4, 
3-1,  10-9 


memory 

changing    11-116  - 
11-117 

11-114 

in  the  workspace  3-1 

requesting    1-3  -  1-4 

saving  1-2 

size    1-3,  1-4 
message,  end-of-file  1-6 
MID$  command  11-92 
minimizing  storage  12-1 
minutes  11-27 
mistakes  in  program  lines 
2-2 

mixing  data  types  7-2 

MOD  command  11-93 

MODE  {Msflium-res)  9-9, 
9-26 

modes 

command  1-3 
edit  1-4 

module 

execution  11-15 
high -resolution  9-31 
medium-resolution   9-8  - 
9-9 

modulus   11-93  11-94 
month  11-27 
mouse  (medium-res)  9-22 
MOVE  (medium-res)  9-9, 

9-27 

move  cursor  1-6 

high-resolution  9-68, 
9-70,  9-73  -  9-75 

move 

backward  (editor)  4-5 
draw  pointer  (high- 
res)  9-125 
graphics  cursor  (high- 
res)  9-95 
the  edit  pointer  4-1 
multipass  compiler  12-1 
multiplication   7-3  -  7-4 
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Index 


natural  exponmt  11-50 

negation  7-3 

nesting  order  (debug)  5-3 

NEXT  command  11-95 
NOT  command  11-96 
not  equal  to    7-3,  7-4,  7-5 
NOT,  logical   11-80  - 11-81 

operator  7-4,  7-7 
null  constants  6-9 
numbers  for  lines  4-5 
numeric 

constants  6-6 

data  conversion    11-162  - 
11-163 

data  types    12-1  -  12-2 

fttnetions  10-7 

type  conversion  11-54, 
11-71 

type  functions  7-9 

ON  ERROR/GOTO 

command    11-97  -  11-99 
ON/GOSUB  command 

11-100  -  11-101 
ON/GOTO  command   11-102  - 

11-103 
OPEN  command  8-3, 

11-104  -  11-105 
operands  7-2 
operators  7-1 

arithmetic   7-3  -  7-4 
equal  7-5 
greater  than  7-5 
hierarchy  of  7-4 
less  than  7-5 
logical  7-7 
relational    7-5  -  7-6 
string  7-6 
types  7-3 
unequal  7-5 

OR 

command  11-106 
logical    11-87  -  11-88 
operator  7-7 


order 

of  nesting  (debug)  5-3 
of  operators  7-4  -  7-5 

OS-9  commands  11-152 
accessing   3-7  -  3-8 

overlay  windows   9-41,  9-107  - 

9-  108 

OWSET  command  (high- 
res)  9-107-9-108 

PACK  command   3-1,  3-8,  3-9, 

10-  9,  12-4 

paint  (high-res)  9-93 
PALETTE  command  (high- 
res)    9-109  -  9-110 
palette 

default  colors  9-79 
high-resolution    9-34  - 

9-35 
registers  9-35 
MRAISJ  cranmand  6-8, 

11-  108  -  11-111 
passing  variables  6-8, 

11-108  -  11-111 
path 

input  11-68 

opening    11-104  -  11-105 
PATTERN  command  (high- 
res)    9-111  -  9-112 
PAUSE  command   5-5,  11-112 
PEEK  command  9-20, 

11-113  -  11-114 
PI  command  11-115 
pixel  9-34 

color  (medium-res) 

0.2S  -  i-i9 
set  (Mfh-PBs)   9-113  - 
9-114 
plus  sign  7-6 
POINT 

high-resolution   9-113  - 
9-114 

medium-resolution  9-10, 
9-28  -  9-29 
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pointer 

draw  (hi-res)  9-42, 
9-125 

draw  (medium-res)  9-12 

eiit  4-1 

file  8-5 

graphics  9-42 

READ  11-140 
POKE  command  9-20,11-116 
POS  command  11-118 
position 

graphics  cursor  (medium- 
res)  9-9 

of  a  record  in  a  file  8-5 

of  cursor  11-118 
power  of  2  11-157 
predefined  windows   9-32  - 
9-33 

PRINT  command  11-119- 
11-120 

debug  5-3 
PRINT  USING  command 
11-122  -  11-128, 
11-180  -  11-182 
printer,  listing  files  3-4 
printing  (tabs)    11-166  - 

11-167 
procedxire 

changing  1-4 
comments    11-135  - 

11-136 
compilation  10-9 
compiling  1-5 
compressing  12-1 
condensing  3-1 
data  size  3-2 
deleting  3-6 
disassembling  3-3 
display  3-1 
displaying  information 

about  3-1 
erasing  3-1, 11-72  - 

11-73 
examining  4-4 
fficecuting  1-5 


procedure  (cont'd) 

execution    2-3,  3-1 
grouping  1-4 
listing   3-2  -  3-3,  4-6 
loading  3-6 
renaming  3-2 
returning  from  11-141 
saving  3-1,  3-5  -  3-6, 

10-  9 
size  3-2 

suspending  11-112 
terminating    11-36  - 

11-  37,  11-161 
tracing  11-174 
writing   2-1  -  2-2 

procedures 

executable  3-8 
executing  11-145  - 

11-147 
loading  3-1 
program 

execution  termination 
1-6 

mistakes  2-2 
modular  1-1 

proportional  text  (high-res) 
9-115  -  9-116 

PROPSW  command  (high- 
res)    9-115  -  9-116 

protect  window  switch  (high- 
res)  9-85 

PUT  command  8-5,  8-6, 
9-117  -  9-118, 
11-129  -  11-130 

PUTGC  command  9-119 

QUIT  (medium-res)  9-10, 

9-30 
quit 

BASIC09    1-5,  3-1 

debug  5-3 

the  editor   2-3,  4-2 

RAD  command  5-2,  11-131 
radians   5-2,  11-131 
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random  access  files    8-5  -  8-11 
and  arrays    8-9  -  8-11 
creating    8-6  -  8-9 
random  value    11-143  - 

1M« 
range  of  numbers  6-2 
READ  8-4,  11-25,  11-132  - 
11-133 

file  access  8-1 

read 

input  11-66  -  11-70 
pixel  color  (medium- 
res)  9-9 

read  a  record   11-58  -  11-60 

real 

constants  6-7 
data  type    6-1  -  6-4 
functions  7-S 
nuinbsr  eonversion 

11-71 
number  range  6-2 
number  rounding  11-53 
record  8-2 

binary  data  11-58 
position  8-5 
rectangle,  drawing  (high- 
res)    9-52  -  9-53,  9-60  - 
9-61 

reduce  memory  size  1-4 
registers  palette    9-35,  9-109  - 
9-110 

relational  operators    7-5  -  7-6 
relative  storage  area  3-3 
REM  command    11-135  - 

11-136 

remainder  (division)  11-93 

removing 

disk  files  11-30 
procedures   3-6,  10-9, 
11-72 

spaces    11-172  -  11-173 
RENAME  command  3-1 
renaming  proeeiares 
renumbering  lines  (editor) 
4-2,  4-10 


REPEAT/UNTIL 

commands    11-137  - 

11-139,  11-179 
requesting  memory    1-3  -  1-4 
resset  file  poftiter  11-148  - 

11-149 

RESTORE  command  11-140 
retrieving  bytes  from  a  file 
8-5 

RETURN  commafti  11-141 

returning 

fi-om  subroutine    11-61  - 

11-62 
to  OS-9  10-9 

reverse  video  (high-res)  9-120 

REVON  command  (high- 
res)  9-120 

rewind  a  file  8-11 

right  brace  1-6 

right  bracket  1-6 

RIGHT$  command  11-142 

ring  bell  9-54 

RND  command   11-143  - 
11-144 

ROOTdrfeetoy  8-7 

rounding  a  real  number 
11-53 

RUN  command  3-1,  6-8,  10-9, 
11-145  -  11-147 

SAVE  command  S.-l,  3-5,  10-9 
saving 

a  window  area   9-96  - 
9-97 

graphic  images  (high- 
res)    9-117  -  9-118 
memory  1-2 
procfedures    S-1,  3-® 
space  by  compiling  1-2 

SCALESW  command  (high- 
res)    9-121  -  9-122 

screen 

alphanumarie  9-i0 
blink  (high-res)  9-55 
clearing  (high-res)  9-64 
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screenicont'd) 

clearing  (medium- 
res)   9-9,  9-17 

color  (medium-res)  9-26 

display  11-122 

format  (medium-res) 
9-26 

formatting  11-180 
location  (medium-res) 

9-20  -  9-21 
resolution  9-31 
selecting  (mefllum- 
res)    9-13  -  9-14 
switching  (medium- 
res)  9-9 
searching 

for  tet  (editor)  4-2,4-9 
in  strings    11-164  - 
11-165 
seconds  11-27 
SEEK  command   11-148  - 
11-149 

select  a  window   9-32  -  9-33 
SELECT  command  (high- 
res)    9-123  -  9-124 
selecting  memory  1-3 
sending  a  carriage  return 
9-67 

sentence-creating 
procedure  4-3 
sequential  file  writes 

11-185  - 11-186 
SETDPTR  command  (high- 
res)  9-125 
setting 

a  point  (medium-res) 

9-10,  9-28  -  9-29 
border  color  (high- 
res)    9-58  -  9-59 
color  (medium-res)  9-18 
pixel  (high-res)   9-113  - 
9-114 

BMM)  pointer  11-140 
screen  (medium-res)  9-9 
SGN  command  11-150- 
11-151 


SHELL  command  11-152- 

11-163 
shell  commands  10-9 
SHIFT-<«-  key  sequence  1-6 
SHIFT-BREAK  key 

sequence  1-6 
SHIFT-CLEAR  key 

sequence  1-6 
show  text    11-119  -  11-121 
sign  of  a  value   11-150  - 

11-151 

simulating  an  error   11-45  - 
11-46 

SIN  command  11-154 
sine  11-154 
single-dlminiicmed  array 

6-9  -  6-10 
SIZE  command    11-155  - 

11-156 
size 

data  3-2 

memory  1-3 

procedure  3-2 
space 

rsCQOviiif   11-172  - 
11-173 

saving  by  compiling  1-2 
spaces  in  command  lines  2-2 
special  keys   1-5  - 1-7 
speed 

of  arithmetic 
functions  12-2 

of  execution  1-1 
SQ  command  11-157 
SQR/SQRT  commands  11-158 
square  root  11-158 
starting 

a  shell  in  a  window  9-36 

BASIC09    1-2  -  1-4 
STATE  command  (debug)  5-3 
statements  10-7 
status  of  joystick  (medium- 
res)    9-22  -  9-23 
STEP  command   5-4,  11-159  - 
11-160 
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step  rate  (debug)  5-4 
stepping  through 

procedures    5-5  -  5-6 
STOP  commaui  11-161 
stop  program  execution  1-6 
storage 

area  of  command 

Unes  3-3 
minimization  12-1 
of  variables    11-31  - 
11-33 

storing 

data    11-25  -  11-26 
in  memory    11-116  - 
11-117 
STR$  command    11-162  - 

11-163 
string 

constants  6-7 

data  conversion    11-181  - 

11-182 
data  type   6-1  -  6-2 
fvmctions  10-7 
length  6-4,11-77 
operators  7-6 
storage  6-5 
variables   6-4  -  6-5 
strings 

appending  7-6 
portioning    11-76,  11-92, 

11-142 
searching  11-164 
structured  programming  1-1 
structures,  complex  data 

8-11  -  8-15 
subroutine 

commands    11-61  -  11-62 
jun^s   11-100  - 11-101 
SUB§TR  command  11-164- 

11-165 
substrings  11-92 
subtracticHi   7-3  -  7-4 
suspending  execution  11-1X2 
switching  screens  (medium- 
res)    9-9,  9-13  -  9-14 


symbolic  debugging  5-1 

syntax  11-1 

system 

commands  3-1 

interfecing  1-1 

TAB  command   11-166  - 

11-167 
TAN  command  11-168 
tangent  11-168 
terminating 

a  procedure    11-36  - 
11-37,  11-161 

the  editor  4-2 
test  for  end-of-file  11-42 
text 

changing    4-2,  4-7  -  4-9 
characters  (high-res) 
9-94 

display    11-119  -  11-121 
fonts    9-43  -  9-44 
formatting    11-122  - 

11-128 
high-resolution   9-42  - 

9-44 

proportional    9-115  - 

9-116 
searching   4-2,  4-9 
cursor  commands  (high- 
res)  9-48 
three-dimension  arrays  6-13 
tilde  1-6 

time   11-27  -  11-28 
feacing 

execution    5-4  -  5-6, 
11-174 

transcendental  functions  10-7 
trapping  errors  11-97  - 11-99 
TRrM$  command  11-172- 

11-173 
TROFF  command  (debug) 

5-4,  11-174 
TRON  command   5-4  -  5-6, 

11-174 
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TRUE  conrniatid   11-175  - 

local  6-7 

11-176 

string   6-4  -  6-5 

turning  off  the  cursor  9-71 

vector  6-13 

two-dimension  array  6-9 

vertical  bar  1-6 

type 

video 

eonversion  8-6,  7-2 

address  (medium-res) 

mismatch  6-6 

9-9 

of  data   6-1  -  6-16,  10-8 

reverse  (high-res)  9-120 

of  file  access  8-1 

visible  cursor  (high-res)  9-72 

of  operators  7-3 

TYPE  command  8-12, 

WCREATE  command   9-33  - 

11-177  - 11-178 

9-34 

WHILE/DO/ENDWHILE 

underscore  1-6 

loop    11-34,  11-41, 

UNDLNOFF  command  (high- 

11-180  -  11-181 

res)  9-126 

whole  number,  range  6-2 

UNDLNON  command  (high- 

wildcard 

res)  9-126 

editor  4-1 

unequal  7-6 

usiDg  witii  commands 

UNTIL   11-137  -  11-139, 

3-5 

11-180 

window 

up  arrow  1-6 

area,  saving    9-96  -  9-97 

UPDATE   8-1,  8-4 

commands  (high-res) 

USIMJ  command  11-180  - 

9-45 

11-182 

deallocating  (high- 

using  debug   5-4  -  5-5 

res)    9-83  -  9-84 

defining  (high-res) 

command  11-181- 

9-86  -  9-87 

11-182 

display   1-6,  9-123  - 

value 

9-124 

absolute  11-4 

erasing  9-91 

Boolean    11-51  -  11-52 

establishing   9-32  -  9-41 

random   11-143  -  11-144 

formats  9-34 

variable 

graphics   9-35  -  9-36 

address    6-8,  11-6 

hardware    9-32  -  9-35 

initialization  6-8 

image  (high-res)    9-101  - 

local  6-7 

9-102 

passing  6-8  -  6-9^ 

overlay  (high-res) 

11-108  -  11-111 

9-107  -  a-lOo 

size    11-155  -  11-156 

protect  switch  (high- 

storage    11-31  -  11-33 

res)  9-85 

value  of  11-78-11-79 

Shell  9-36 

variables  11-2 

warktog  area  (high-res) 

assigning  (debug)  5-3 

16 

Index 


windows 


writing 


defining    9-33  -  9-34 
fromBASIC09  9-39- 


a  procedure  2-1  -  2-2 
to  files   8-3,  11-129 


9-41 


overlay  9-41 


XOR  command   11-187  - 

11-188 
XOR  operator  7-7 


predefined  9-32  -  9-33 
with  high-resolution 


9-31 
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workspace    1-3,  3-1 
WRITE  command    11-185  - 
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Chapter  1 


System  Organization 


OS-9  is  composed  of  a  group  of  modules,  each  of  which  has  a  spe- 
cific function.  The  following  illustration  shows  the  m^or  mod- 
ules. Actual  module  names  are  capitalized. 


I/O  System  Modules 


INIT 


OS-9  KERNEL 
(0S9P1.  0S9P2) 


Input  Output  Manager 
(lOMAN) 
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Disk  File 
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Color  Computer  OS-9  Modules 

lOMAN  Input/output  management 

INIT  System  initialization  table 

CLOCK  ^ftmure  routine  time  management 

RBP  Bandom  block  file  management 

SCF  Sequential  character  file  management 

PIPEMAN  Pipe  file  management 

CC3DISK  Color  Computer  disk  driver 

CC3I0  Color  Computer  input/output  dxiv^^ 

The  VDGINT  (victeo  display  ^smcsHm)  provides  boifh  iat^fece 
functions  and  low-level  routines  for  Color  Computer  2  VDG 

compatibility. 

The  GRFINT  interface  provides  high-level  graphics  code  interpre- 
tation and  interface  functions. 

The  WINDINT  interface  contains  all  the  functions  of  GRFINT, 
along  with  additional  support  for  Multiview  functions.  If  you  are 
using  Multiview,  exclude  GRFINT  from  the  system. 

Both  WINDINT  and  GRFINT  use  the  low-level  driver  GRFDRV 
to  perform  the  actual  drawing  an  bitmap  screens. 

Term_VDG  uses  CC3I0  and  VDGINT.  TERM_WIN  and  all 
window  descriptors  (W,  Wl,  W2,  and  so  on)  use  CC3I0,  WIN- 
DINT, GRFINT,  and  GRFDRV  modules. 

Kernel,  Clock  Module,  and  INIT 

The  system's  first  level  contains  the  kernel,  clock  module,  and 
INIT. 

Hie  kernel  provides  basic  system  services,  such  as  multitaildng 
and  memory  management.  It  links  all  other  OS-9  modules  into 

the  system. 

The  clock  module  is  a  software  handler  for  the  real-time  clock 
hardware. 

INIT  is  an  initialization  table  used  by  the  kernel  during  system 
startup.  This  table  loads  initial  tasks  and  specifies  initial  table 
sizes  and  initial  system  device  names.  It  is  loaded  into  RAM 
(random  access  memory)  by  the  OS-9  bootstrap  module  Boot. 
Boot  also  loads  the  OS9P2  and  INIT  modules  during  system 
startup. 
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There  are  two  ways  to  run  boot: 

•  Using  the  DOS  command  with  Color  Disk  BASIC,  Ver- 
sion 1.1,  or  later. 

•  Pressing  the  reset  button  after  OS-9  is  running. 

Input/Output  Modules 

Tbm  rmaittittg  M£>dttlei  m&lm  uf  the  (M-B  I/O  $^sim3..  They 
defined  briefly  here  and  are  discussed  in  detail  in  Chapter  4. 

I/O  Manager 

The  system's  second  level  (the  level  below  the  kernel)  contains 
the  input/butput  manager,  lOMAN.  The  I/O  manager  provides 
common  processing  for  all  input/output  operations.  It  is  required 
for  performing  any  input/output  supported  by  OS-9. 

File  Managers 

The  system's  third  level  contains  the  file  managers.  File  man- 
agers perform  I/O  request  processing  for  similar  classes  of  I/O 
devices.  There  are  three  file  managers: 

RBF  manager  The  random  block  file  manapr  processes 
all  disk  I/O  op^atiOBS. 

SCF  manager  The  sequential  character  file  manager  han- 
dles all  non-disk  I/O  operations  that  operate 
one  character  at  a  time.  These  operations 
include  terminal  and  printer  I/O. 

PIPEMAN  The  pipe  file  manager  handles  pipes.  Pipes 

are  memory  bufltors  that  atst  as  files.  Mpes 
are  used  for  data  transfers  between 
processes. 

Device  Drivers 

The  system's  fourth  level  contains  the  device  drivers.  Device 
drivers  handle  basic  I/O  functions  for  specific  I/O  controller  hard- 
ivare.  Ifeu  i^a  use  pt^'WAUm.  ^v&es,  or  you  can  write  your 
own. 
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Device  Descriptors 

The  system's  fifth  level  contains  the  device  descriptors.  Device 
descriptors  are  small  tables  that  define  the  logical  name,  device 
driver,  and  file  manager  for  each  I/O  port.  They  also  contain  port 
initialization  and  port  address  information.  Device  descriptors 
require  only  one  copy  of  each  I/O  controller  driver  used. 

Shell 


The  shell  is  the  command  interpreter.  It  is  a  program  and  not  a 
part  of  tite  operating  system.  The  shell  is  fully  described  in  the 
OS-9  Commands  manual. 
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The  kernel  is  the  core  of  OS-9.  The  kernel  supervises  the  system 
and  manages  system  resources.  Half  of  the  kernel  (called 
0S9P1)  resides  in  the  boot  module.  The  other  half  of  the  kernel 
(called  OS9P2)  is  loaded  into  RAM  with  the  other  OS-9  modules. 

The  kernel's  main  functions  are: 

•  System  initialization  after  reset 

•  Service  request  processing 

•  Memory  management 

•  Multiprogramming  management 

•  Interrupt  processing 

I/O  functions  are  not  included  in  the  list  because  the  kernel  does 

not  directly  process  them.  Instead,  it  passes  I/O  system  calls  to 
the  I/O  Manager  for  processing. 

System  Initialization 

After  a  hardware  reset,  the  kernel  initializes  the  system.  This 

involves: 

1.  Locating  modules  loaded  in  memory  from  the  OS-9  Boot  file. 

2.  Determining  the  amount  of  available  RAM. 

3.  Loading  any  reqtiired  modules  that  were  not  loaded  from  the 
OS-9  Boot  file. 

OS-9  Level  Two  cannot  Install  new  system  calls  using  the  OS-9 

Level  One  system  call  F$SSvc.  F$SSvc  does  not  work  with  a 
Level  Two  user  program  because  of  the  separation  of  system  and 
user  address  space. 
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OS9P3  can  be  used  to  tailor  the  system  to  fit  specific  needs.  The 
following  listing  is  an  example  of  how  to  use  the  OS9P3  module. 
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Module  Header 

m\s 

sect 

Type 

set 

Systin*Objct 

Revs 
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ReEntM 

mv 

tm 
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mod 

DS9End,DS9Naiiie,Type,RevS)Cold,256 

UK 

4F53397B  0S9Name 
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MK 
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um 

MM 

Routine  Cold 

0M45 

nm 
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Mm 

SlBDJyi  Cold 
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Mm 
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F$SSvc    install  new  service 
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mm 

•Service  call  Say  Hello  to 

user 

mm 

• 

mi\ 

♦inputs 

U  =  Registers  ptr 

mn 

• 

R$X,u  =  Message  ptr  (if  ! 

send  default) 

«m 

* 

Max  message  length  '  4!  bytes. 

mn 

♦ 

•Output; 

Message  sent  to  standard  error  path  of  user. 

mn 

•Data; 

D.Proc 

mn 
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5ayHi6 

bra  if  not  default 

msi 

U22 

ie9ESI! 

Idy 

D.Proc 

get  proc  descr  ptr 

ms3 

et26 

EE24 

Idu 

P>SP,y 

get  caller's  stack 

um 

ms 

33C8D8 

leau 

■48,11 

room  for  message 

nm 

96DJ 

Ida 

D.SysTsfc 

system's  task  num 

m% 

U2d 

ES26 

Idb 

P$TflSK,y 

caller's  tast  num 

msi 

mf 

ie8Eee28 

Idy 

Hi 

set  byte  count 

mm 

tm 

3880(112 

leaii 

Hello, per 

destination  ptr 

mii 

mi 

1B3F3B 

0S3 

FJMove 

mess  into  user  mem 

um 

3BC4 

leax 

e,u 

um 

im 

nmm 

SayHiS  Idy 

m 

get  lix  b|fte  csant 

ami 

tm 

iisi: 

Idn 

D.Proc 

get  proc  deic  ptr 

(Jigs 

tin 

fleCB32 

Ida 

PtPflTHtS.u  ptth  m  of  stderr 

um 

1B3F8C 

0S9 

HWritLn 

write  mess  line 

UKi 

39 

rts 

um 
mm 

im 

48656C6C 

Hello  fa 

"Hello  there  user." 

mm 

im 

(D 

fcb 

ID 

um 
mu 

eesB 

51(486 

emod 

module  CRC 
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lim    m  BSSEnd  eqii 

um 

End 

Um  errorCs) 
nUi  warningCs) 

UKi  iBM4  pragfan  iytes  |eiier»teiJ 
mil  um  ifctatytes  allocated 
$2884  1B372  bytes  ttsed  for  symbols 

System  Call  Processing 

System  calls  are  used  to  communicate  between  OS-9  and  assem- 
My-lattgm*^  pwgpaMS  fc  mA  fliiftetions  as  memory  allocation 
and  process  creation.  In  addition  to  I/O  and  memory  manage- 
ment functions,  system  calls  have  other  functions.  These  include 
intes^Oeess  control  and  timekeeping. 

System  calls  use  the  SW12  instruction  followed  by  a  constant 
byte  representing  the  code.  You  usually  pass  parameters  for  sys- 
tem calls  in  the  6809  registefs. 

OS9D0fs  and  Symbolic  Names 

A  system-wide  assembly-language  equate  file,  called  0S9Defs, 
defines  symbolic  names  for  all  system  calls.  This  file  is  included 
when  assembling  hand-written  or  compiler-generated  code.  The 
OS-9  assembler  has  a  built-in  macro  to  generate  system  calls, 
fcr  (Mm^le: 

□  S9   I  $ Read 
is  recognized  and  assembled  as  equivalent  to: 
SWI2 

FGB  I* Re ad 

The  OS-9  assembly  macro  0S9  generates  an  SWI2  function.  The 
label  I$Read  is  the  label  for  the  code  $89. 

Types  of  System  Calls 

System  calls  are  divided  into  two  categories,  I/O  chills  and  func- 
tion calls. 
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I/O  calls  perforin  various  input/output  fiinctions.  The  kernel 
passes  calls  of  this  type  to  the  FO  Mtaaf^  fiar  pPOCSBSMng.  "Kie 
symbolic  names  for  I/O  calls  begin  with  1$.  Ebr  example,  the 

Read  system  call  is  called  I$Read. 

Function  calls  perform  memory  management,  multi-program- 
ming, and  other  functions.  Most  are  processed  by  the  kernel.  The 
symbolic  names  for  function  calls  begin  with  F$.  For  example, 
the  Link  function  call  is  called  f:$Uak. 

The  function  calls  include  aser  mlUi  and  privileged  system  rawjcfe 
calls.  (See  Chapter  8,  "System  Calls",  for  more  information.) 

Memory  Management 

Memory  management  is  an  important  operating  system  function. 
Using  memory  modules,  OS-9  manages  the  logical  contents  of 
memory  and  the  physical  assignment  of  memory  to  programs. 

All  programs  that  are  loaded  must  be  in  the  memory  module  for- 
mat. This  format  allows  OS-9  to  maintain  a  module  directory  of 
all  the  programs  in  memory.  The  directory  contains  information 
about  each  module,  including  its  name  and  address  and  the 
vms^&m  dt  procgiies  usii3f  it.  The  njomber  of  processes  u^ng  a 
module  is  (Mlled  tibie  moduk's  mmt. 

When  a  module's  link  count  is  zero,  OS-9  deallocates  its  part  of 
memory  and  removes  its  name  from  the  module  directory. 

Memory  modules  are  the  foundation  of  OS-9's  modular  software 
environment.  Advantages  of  memory  management  are: 

•  Automatic  runtime  linking  of  pro-ams  to  libraries  of 
utility  modules 

•  Automatic  sharing  of  re-entrant  programs 

•  Replacement  of  small  sections  of  large  programs  into 
memory  for  update  or  correction 

Memory  Use 

OS-9  reserves  some  space  at  the  top  and  bottom  of  RAM  for  its 
own  use.  The  amount  depends  on  the  sizes  of  system  tables  that 
are  specified  in  the  ENIT  modute. 
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OS-9  pools  all  other  RAM  into  a  free  memory  space.  As  the  sj^S- 
tem  allocates  or  deallocates  memory,  it  dynamically  takes  it 
from  or  returns  it  to  this  pool.  RAM  does  not  need  to  be  contig- 
uous because  the  memory  management  unit  can  dynamically 
rearrange  memory  addresses. 

The  basic  unit  of  memory  allocation  is  the  256-byte  page.  OS-9 
always  allocates  memory  in  whole  numbers  of  pages. 

The  data  structure  that  OS-9  Level  Two  uses  to  keep  track  of 
memory  allocation  is  a  256-byte  bit  map.  Each  bit  in  this  table 
is  associated  with  a  specific  page  of  memory.  A  cleared  bit  indi- 
cates that  the  page  is  free  and  available  for  assignment.  A  set 
bit  indicates  that  the  page  is  in  use  (that  no  RAM  is  free  at  that 
address).  OS-9  Level  Two  always  allocates  memory  in  8192-byte 
increments.  This  is  the  smallest  memory  block  that  the  memory 
management  hardware  supports. 

OS-9  automatically  allocates  memory  when  any  of  the  following 

occurs: 

•  Program  modules  are  loaded  into  RAM 

•  Processes  are  created 

•  Processes  execute  system  calls  to  request  additional 


OS-9  also  hm  iiMiM  fte^ESS  to  deaUoiate  wmmxf  allocated 
to  pi^p^am  woiolii,  mm  processeiK,  buftrs,  mmd  taMes. 

In  general,  memory  for  program  modules  and  buffers  is  allocated 
from  high  addresses  downward.  Memory  for  process  data  areas  is 
allocated  from  low  addresses  upward. 

Following,  is  a  memory  map  of  a  typical  system.  Actual  memory 
sizes  and  addresses  can  vary  depending  on  the  exact  system 


RAM 


tables 
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Color  Computer  OS-9  Typical  Memory  Map 


I/O  Device  ijid^es^s 


Reserved  I/O  Devices 


Reserved  Common  Memory 


OS-9  Kernel 


Bottom  of  Memory 
in  a  128K  System 


Bottom  of  Memory 
in  a  512K  System 


$7FFFF 

$7FF00 
^  $7FE80 

^  $7FE00 
varies 

$60000 

^  $00000 


Figure  2,1 

Note:  The  high  two  pages  of  every  logical  address  space 
contain  the  defined  areas  I/O  Device  Addresses,  Reserved 
I/O  Devices,  and  Reserved  Common  Memory. 


Memory  Management  Hardware 

The  8-bit  CPU  in  the  Color  Computer  3  can  directly  address  only 
64  kilobytes  of  memory  using  its  16  address  lines  (A0-A15).  The 
Color  Computer  3's  Memory  Management  Unit  (MMU)  extends 
the  addressing  capability  of  the  computer  Igr  imcareaslng  the 
address  lines  to  19  (A0-A18).  This  lets  the  computer  address  up 
to  512  kilobytes  of  memory  ($0-$7FFFF). 

The  512K  address  space  is  called  the  physical  address  space.  The 
physical  address  space  is  subdivided  into  8K  blocks.  The  six  high 
order  address  bits  (A13-A18)  define  a  block  number. 
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OS-9  creates  a  bgical  address  space  of  up  to  64K  for  each  task 
by  using  the  FORK  system  call.  Evea  though  the  memory 

within  a  logical  address  space  appears  to  be  cofltiguous,  it  might 
not  be — the  MMU  translates  the  physical  addresses  to  access 
available  memory.  Address  spaces  can  also  contain  blocks  of 
memory  that  are  common  to  more  than  one  map. 

The  MMU  consists  of  a  multiplexer  and  a  16  by  6-bit  RAM 
airay.  Each  of  the  6-bit  elemmts  in  this  array  is  an  MiSflU  task 

register.  The  computer  uses  these  task  registers  to  determine 
the  proper  8-kilobyte  memory  segment  to  address. 

The  MMU  task  registers  are  loaded  with  addressing  data  by  the 
CPU.  This  data  indicates  the  actual  location  of  each  8-kilobyte 
segment  of  the  current  system  memory.  The  task  registers  are 
divided  into  two  sets  consisting  of  eight  registers  men.  Whether 
the  task  register  select  bit  (TR  bit)  is  set  or  reset,  determines 
which  of  the  two  sets  is  to  be  used. 


The  relation  between  the  data  in  the  task  register  and  the  gen- 
erated addresses  is  as  follows: 


Bit 

D5 

D4 

D3 

D2 

Dl 

DO 

Corresponding 
Memory  Addlress 

A18 

A17 

A16 

A15 

A14 

A13 

Figure  2.2 

When  the  CPU  accesses  any  memory  outside  the  1/0  and  control 
range  (XFFOO  =  XFFFF),  the  CPU  address  lines  (A13-A15)  and 
the  TR  bit  determine  what  segment  of  memory  to  address.  This 
is  done  through  the  multiplexer  wh^  SELECT  is  low.  (See  the 

following  table.) 

When  the  CPU  writes  data  to  the  MMU,  A0-A3  determine  the 
location  of  the  MMU  register  to  receive  the  incoming  data  when 
SELECT  is  high.  The  following  diagram  illustrates  the  operation 
of  the  Color  Computer  3's  memory  management: 
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D0-D5   

CPU  data 

A13-A15  _^ 

TRbit   


A0-A3 


Multiplexer 


[> 


RAM 


SELECT 


Dout 
RA0-RA3 

WE 

 e  


A13-A18 


Figure  2.3 

The  system  uses  the  data  from  the  MMU  registers  to  determine 
the  block  of  memory  to  be  accessed,  according  to  the  following 
table: 


TR 

MMU 

Bit 

A15  A14  A13 

AddressRange 

Address 

0 

0 

0 

0 

XOOOO-XIPFF 

FFAO 

0 

0 

0 

1 

X2000-X3FFF 

FFAl 

0 

0 

1 

0 

X4000-X5FFF 

FFA2 

0 

0 

1 

1 

X6000-X7FFF 

FFA3 

0 

1 

0 

0 

X8000-X9FFF 

FFA4 

0 

1 

0 

1 

XAOOO-XBWF 

FFA5 

0 

1 

1 

0 

XCOOO-XDFFF 

FFA6 

0 

1 

1 

1 

XEOOO-XFFFF 

FFA7 

1 

0 

0 

0 

XOOOO-XIFFF 

FFA8 

1 

0 

0 

1 

X2000-X3FFF 

FFA9 

1 

0 

1 

0 

X4000-X5FFF 

FFAA 

1 

0 

1 

1 

X6000-X7FFF 

FFAB 

1 

1 

0 

0 

X8000-X9FFF 

FFAC 

1 

1 

0 

1 

XAOOO-XBFFF 

FFAD 

1 

1 

1 

0 

XCOOO-XDFFF 

FFAE 

1 

1 

1 

1 

XEOOO-XFFFF 

FFAF 

Figure  2.4 
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The  translation  of  physical  address  to  8K-blocks  is  as  &lIows: 


Range 

Mock 

Number 

Number 

Prom 

To 

From 

To 

00000 

OlFFF 

00 

40000 

41FFF 

20 

02000 

dSFFF 

01 

42000 

43PFP 

21 

04000 

05FFF 

02 

44000 

45FFF 

22 

06000 

07FFF 

03 

46000 

47FFF 

23 

08000 

09FFF 

04 

48000 

49FFF 

24 

OAOQO 

OBFFF 

05 

4A000 

4BFFF 

25 

ocooo 

ODFPF 

06 

4CD00 

4WWW 

26 

OliOOO 

07 

4rj000 

4rif  J?r 

27 

10000 

IIFFF 

08 

50000 

51FFF 

28 

12000 

13FFF 

09 

52000 

53FFF 

29 

14000 

15FFF 

OA 

54000 

55FFF 

2A 

16000 

17FFF 

OB 

56000 

57FFF 

2B 

18000 

19FFP 

OC 

58000 

59PFF 

2C 

lAOOO 

IBFFF 

OD 

5A000 

5BFFF 

2D 

ICOOO 

IDFFF 

OE 

5C000 

5DFFF 

2E 

lEOOO 

IFFFF 

OP 

5E000 

5FFFF 

2P 

20000 

21FFF 

10 

60000 

61FFF 

30 

22000 

23FFF 

11 

62000 

63FFF 

31 

24000 

25FFF 

12 

64000 

65FPP 

32 

26000 

27FFF 

13 

66000 

67FFF 

33 

28000 

29FFF 

14 

68000 

69FFF 

34 

2A000 

2BFPF 

15 

6A00O 

6BFFF 

m 

2G000 

2DFFF 

16 

6C000 

6DFFF 

36 

2E000 

2FFFF 

17 

6E000 

6FFFF 

37 

30000 

31FFF 

18 

70000 

71FFF 

38 

32000 

33FFF 

19 

72000 

73FFF 

39 

34000 

35FFF 

lA 

74000 

75FFF 

3A 

36000 

37FFF 

IB 

76000 

77PPP 

3B 

38000 

39PPP 

IC 

78000 

79FFF 

3C 

3A000 

3BFFF 

ID 

7A000 

7BFFF 

3D 

3C000 

3DFFF 

IE 

7C000 

7DFFF 

3E 

3E000 

3FPPF 

IF 

7E000 

7FFFF 

3F 

Figure  2.5 
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In  order  for  the  MMU  to  function,  the  TR  bit  at  $FF90  must  be 
cleared  and  the  MMU  must  be  enabled.  However,  before  doing 

this,  the  address  data  for  each  memory  segment  must  be  loaded 
into  the  designated  set  of  task  registers.  For  example,  to  select  a 
standard  64K  map  in  the  top  range  of  the  Color  Computer  S's 
512K  RAM,  with  the  TR  bit  set  to  0,  the  following  values  must 
be  preloaded  into  the  MMU's  registers: 


MMU 

Location 

Data 

Data 

Address 

Address 

(Hex) 

(Bin) 

Range 

FFAO 

38 

111000 

70000-71FFF 

FFAl 

39 

111001 

72000-73FFF 

FFA2 

3A 

111010 

74000-75FFF 

FFA3 

3B 

111011 

76000-77FFF 

FFA4 

3C 

111100 

78000-79FFF 

FFA5 

3D 

111101 

7A000-7BFFF 

FFA6 

3E 

111110 

7C000-7DFFF 

FFA7 

3F 

mill 

7E000-7FFFF 

Figure  2.6 

Although  this  table  shows  MMU  data  in  the  range  $38  to  3F, 
any  data  between  $0  and  $3F  can  be  loaded  into  the  MMU  reg- 
isters to  select  memory  addresses  in  the  range  0  to  $7FFFF,  as 
illustrated  by  Figure  2.5. 

Normally,  the  blocks  containing  1/0  devices  are  kept  in  the  sys- 
tem map,  but  not  in  the  user  maps.  This  is  appropriate  for  time- 
sharing applications,  but  not  for  process  control.  To  directly 
access  I/O  devices,  use  the  F$MspBlk  system  call.  This  call 
takes  a  starting  block  number  and  block  count,  and  maps  them 
into  unallocated  spaces  of  the  process's  address  space.  The  sys- 
tem call  returns  the  logical  address  at  which  the  blocks  were 
inserted. 

Fbr  eisample,  suppose  a  dtspilay  screen  in  your  system  is  allo- 
cated at  extended  addresses  $7A000-$7DFFF  (blocks  3D  and 
3E).  The  following  system  call  maps  them  into  your  address 
space: 

Idb         #2  number  of  blocks 

Idx         #3D  starting  block  number 

os9         F$MapBlk     call  MapBlk 

stu         lOPorts       save  address  where  mapped 
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On  return,  the  U  register  contains  the  starting  address  at  which 
the  blocks  switehii.  Ibr  example,  suppose  tet  the  call 
returned  $4000,  To  access  extended  adidress  $7A020,  write  to 

$4020. 

Other  system  calls  that  copy  data  to  or  from  one  task's  map  to 
another  are  available,  such  as  F$STABX  and  F$Move.  Some  of 
these  calls  are  system  mode  jaivileged.  You  can  unprotect  them 
by  changing  the  appropriate  bit  in  eowesponding  entry  of 
the  system  service  request  table  and  then  making  a  new  system 
boot  with  the  patched  table. 

Multiprogrraming 

OS-9  is  a  multiprofMrnmlng  operating  system.  This  means  that 
several  independent  programs  called  processes  can  be  executed  at 
the  same  time.  By  issuing  the  appropriate  system  call  to  OS-9, 
each  process  can  have  access  to  any  system  resource. 

Multiprogramming  functions  use  a  hardware  real-time  clock. 
The  clock  generates  interrupts  60  times  per  second,  or  one  every 
16.67  milliseconds.  These  ialemipis  am  called  ticks. 

Proeesses  that  are  not  waiting  for  some  event  are  called  active 
processes.  OS-9  runs  active  processes  for  a  specific  system- 
assigned  period  called  a  time  slice.  The  number  of  time  slices 
per  minute  durii^  which  a  process  is  allowed  to  execute  depends 
on  a  process's  priority  relative  to  all  other  active  processes. 
Many  OS-9  system  calls  are  available  to  create,  terminate,  and 
control  processes. 

Process  Creation 

A  process  is  created  when  an  existing  process  executes  a  Fork 
system  call  (F$Fork).  This  call's  mala  aEegwawat  is  the  name  of 
the  program  module  that  the  new  process  is  to  execute  first  (the 
primary  module). 

Finding  the  Module.  OS-9  first  attempts  to  find  the  module  in 

the  module  directory.  If  it  does  not  find  the  module,  OS-9  usu- 
ally attempts  to  load  into  memory  a  mass-storage  file  in  the  exe- 
cution directory,  with  the  requested  module  name  as  a  filename. 
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Assigning  a  Process  Descriptor.  Once  OS-9  finds  the  module, 
it  assigns  the  process  a  data  structure  called  a  process  descrip- 
tor-. TMS'  ii  a  64-byte  package  that  contains  information  about 
the  process,  its  state  (see  the  following  section  "Process  States"), 
memory  allocations,  priority,  queue  pointers,  and  so  on.  OS-9 
automatically  initializes  and  maintains  the  process  descriptor. 
The  process  itself  cannot  access  the  descriptor;  it  has  no  need  to 
do  so. 

Allocate  RAML  The  next  step  is  to  allocate  RAM  for  the  pro- 
cess. The  primary  module's  header  contains  a  storage  size.  OS-9 
uses  this  size  unless  the  Fork  system  call  requests  a  larger  area. 
OS-9  then  attempts  to  allocate  a  memory  area  of  the  specified 
size  from  the  free  memory  space.  The  memory  space  does  not 
need  to  be  contiguous. 

Proceed  or  Terminate.  If  OS-9  can  perform  all  of  the  previous 
steps,  it  adds  the  new  process  to  the  active  process  queue  for  exe- 
cution scheduling.  If  it  cannot,  it  terminates  the  creation;  the 
process  that  originated  the  Jbrk  is  informed  of  the  error. 

Assign  Process  ID  and  User  ID.  OS-9  assigns  the  new  process 
a  unique  number  called  a  process  ID.  Other  processes  can  com- 
monicftte  with  the  process  by  refertng  to  its  ID  in  variolas  sys- 
tem calls. 

The  process  also  has  a  user  ID,  which  is  used  to  identify  all  pro- 
cesses and  files  belonging  to  a  particular  user.  The  user  ID  is 
inherited  from  the  parent  process. 

Process  Termination.  A  process  terminates  when  it  executes 
an  Exit  system  call  (F$Exit)  or  when  it  receives  a  fatal  signal. 
The  tennimtim  clos^  mf  apeia  patjbs,  deaUocate^  memory  used 
by  the  process,  and  unlinks  its  primary  module. 

Process  States 

At  any  instant  a  process  can  be  in  one  of  three  states: 

•  Active — The  process  is  ready  for  execution. 

•  Waiting — The  process  is  suspended  until  a  child  process 
terminates  or  until  it  receives  a  signal.  A  child  process 
is  a  process  that  is  started  (execution  is  begun  by) 
anofi^  peoeem—@.  pmmt  process . 
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•  Sleeping — The  process  is  suspended  for  a  specifie  period 

of  time  or  until  it  receives  a  signal. 

Each  state  has  its  own  queue,  a  linked  list  of  descriptors  of  pro- 
cesses in  that  state.  To  change  a  process's  state,  move  its 
descriptor  to  another  queue. 

The  Active  State,  Each  active  process  is  given  a  time  slice  for 
execution,  accordinf  to  Its  pdoritf .  The  sAedtife  in  tiaa  kernel 
ensures  that  all  active  processes,  even  those  of  low  priority,  get 

some  CPU  time. 

The  Wait  State.  This  state  is  entered  when  a  process  executes  a 
Wait  system  call  (F$Wait).  The  process  remains  suspended  until 
one  of  its  child  proceiseg  terminates  or  until  it  receives  a  signal. 
(See  the  "Signals'*  section  laitar  in  this  ^pter  J 

The  Sleeping  State.  This  state  is  enteted  when  a  process  exe- 
cutes a  Sleep  system  call  (F$Sleep),  which  specifies  the  number 
of  ticks  for  which  the  process  is  to  remain  suspended.  The  pro- 
cess remains  asleep  until  the  specified  time  has  elapsed  or  until 
it  receives  a  wakeup  signal. 

Execution  Scheduling 

The  OS-9  scheduler  uses  an  algorithm  that  ensures  that  all 
active  processes  get  some  execution  time. 

All  active  processes  are  members  of  the  active  process  queue, 
which  is  kept  sorted  by  process  age.  Age  is  the  number  of  process 
sWittsheg  Imt  have  Dccurfed  since  the  |M*ocess*a  last  time  slice. 
When  a  process  is  moved  to  the  active  process  queue  from 
another  queue,  its  age  is  set  according  to  its  priority — the  higher 
the  priority,  the  higher  the  age. 

Whenever  a  new  process  becomes  active,  the  ages  of  all  other 
active  processes  increase  by  one  time  slice  count.  When  the  exe- 
cuting process's  time  slice  has  elapsed,  the  schedulra"  selects  the 
next  process  to  be  executed  (the  one  with  the  next  highest  age, 
the  first  one  in  the  queue).  At  this  time,  the  ages  of  all  other 
active  processes  increase  by  one.  Ages  never  go  beyond  255. 

A  new  active  process  that  was  terminated  while  in  the  system 
state  is  an  exception.  This  process  is  given  high  priority  because 
it  is  usually  executing  critical  routines  that  affect  stewii  ^stem 
resources. 
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When  there  are  no  active  processes,  the  kernel  handles  the  next 
interrupt  and  then  executes  a  CWAl  instruction.  This  procedure 
decreases  interrupt  latency  time  (the  time  it  takes  tifcte  systam  to 
process  an  interrupt). 

Signals 

A  signal  is  an  asynchrcsnous  control  mechanism  used  for  inter- 
process communication  and  control.  It  behaves  like  a  software 
interrupt.  It  can  cause  a  process  to  suspend  a  program,  execute 
a  specific  routine,  and  then  return  to  the  interrupted  program. 

Signals  can  be  sent  from  one  process  to  another  process  by  the 
Send  system  call  (F$Send).  Or,  they  can  be  sent  from  OS-9  ser- 
vice routines  to  a  process. 

A  signal  can  convey  status  infiirmation  in  the  &rm  rf  a  1-I3yte 
numeric  value.  Some  signal  codes  (values)  are  predefined,  but 
you  can  define  most.  The  signal  codes  are: 

0  =   Kill  (terminates  the  process,  is  non- 

interceptable) 

1  =  Wakeup  (wakes  up  a  sleeping  process) 

2  =  Keyboard  terminate 

3  =  Keyboard  interrupt 

4  =  Window  change 

128-255  =  User  defined 

When  a  signal  is  sent  to  a  process,  the  signal  is  iawsd  in  the 
process  descriptor.  If  the  process  is  in  the  sleeping  or  waiting 
state,  it  is  changed  to  the  active  state.  When  the  process  gets  its 
next  time  slice,  the  signal  is  processed. 

What  happens  next  depends  on  whether  or  not  the  process  has 
set  up  a  signal  intercept  trap  (signal  service  routine)  by  execut- 
ing an  Intercept  system  call  (F$Icpt). 

If  ftg  p-ocess  has  set  up  a  signal  intercept  trap,  the  process 
resumes  execution  at  the  address  given  in  the  Intercept  call.  The 
signal  code  passes  to  this  routine.  Terminate  the  routine  with 
an  RTI  instruction  to  resume  normal  execution  of  the  process. 
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Note:  A  wakeup  signal  activates  a  sleeping  process.  It  sets 
a  flag  but  ignores  the  call  to  branch  to  the  intercept 
routine. 

If  it  has  not  set  up  a  signal  intercept  trap,  the  process  is  termi- 
nated immediately.  It  is  also  terminated  if  the  signal  code  is 
zero.  If  the  process  is  in  ihe  S3rst^  mode,  OS-9  d^ers  the  termi- 
nation. The  process  dies  upon  return  to  the  Msec  state. 

A  process  can  have  a  signal  pending  (usually  because  the  pro- 
cess has  not  been  assigned  a  time  slice  since  receiving  the  sig- 
nal). If  it  does,  and  another  process  tries  to  send  it  another 
signal,  the  new  signal  is  terminated,  and  the  Send  system  call 
returns  an  &tc&t.  %  gi^  the  desftination  process  iime  to  p^oeess 
the  pending  signal,  the  sender  needs  to  execute  a  Sleep  system 
call  for  a  few  ticks  before  trying  to  send  the  signal  again. 

Interrupt  Processing 

Interrupt  processing  is  another  important  function  of  the  kernel. 
OS-9  sends  each  hardware  interrupt  to  a  specific  address.  This 
address,  in  turn,  specifies  the  address  of  the  device  service  rou- 
tine to  be  executed.  This  is  called  vectoring  the  interrupt.  The 
address  that  points  to  the  routine  is  called  the  vector.  It  has  the 
same  name  as  the  interrupt. 

The  SWT,  SWI2,  and  SWI3  vectors  point  to  routines  that  read 
the  corresponding  pseudo  vector  from  the  process's  descriptor 
and  dispatch  to  it.  This  is  why  the  Set  SWI  system  call 
(F$SSWI)  is  local  to  a  process;  it  only  changes  a  pseudo  vector  in 

the  process  descriptor. 

Hardware  Vector 


Table 


Vector 


Address 


SWI3 

SWI2 

FIRQ 

IRQ 

SWI 

NMI 


$FFF2 
$FFF4 
$FFF6 
$FFF8 
$FFFA 
$FFFC 
$FFFE 


RESTART 
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FIRQ  Interrupt.  The  system  uses  the  FIRQ  interrupt.  The 
FIRQ  vector  is  not  available  to  you.  The  FIRQ  vector  is  reserved 
for  future  use.  Only  one  FIRQ  generating  device  can  be  in  the 
system  at  a  time. 

Logical  Interrupt  PoUing  %stem 

Because  most  OS-9  I/O  devices  use  IRQ  inteTrupts,  OS-9 

includes  a  sophisticated  polling  system.  The  IRQ  polling  system 
automatically  identifies  the  source  of  the  interrupt,  and  then  exe- 
cutes its  assoeiated  user-  or  system-defined  service  routine. 

IRQ  Interrupt.  Most  OS-9  I/O  devices  generate  IRQ  interrupts. 
The  IRQ  vector  points  to  the  real-time  clock  and  the  k^board 
scanner  nnitines.  These  routines,  in  turn,  jump  to  a  special  IRQ 

polling  system  that  determines  the  source  of  the  interrupt.  The 
polling  system  is  discussed  in  the  next  section,  "Logical  Inter- 
rupt Polling  System." 

NMI  Interrupt.  The  system  uses  the  NMI  interrupt.  The  NMI 
vector,  which  points  to  the  disk  driver  interrupt  service  routine, 
ig  not  available  to  you. 

The  PolliMg  "Ribte.  The  infermation  required  for  IRQ  polling  is 
maintained  in  a  data  structure  called  the  IRQ  polling  table.  The 
table  has  a  9-byte  entry  for  each  device  that  might  generate  an 
IRQ  interriilplw  The  table  size  is  permanent  and  is  defined  by  an 
initialization  constant  in  the  INIT  module.  Each  entry  in  the 
polling  table  is  given  a  number  from  0  (lowest  priority)  to  255 
(highest  priority).  In  this  way,  the  more  important  devices  (those 
that  have  a  higher  interrupt  frequency)  can  be  polled  before  the 
less  important  ones. 

Each  entry  has  six  variables: 

Polling  Address     Points  to  the  status  register  of  the  device. 

The  registrar  must  have  a  bit  or  bits  that 
indicate  if  it  is  the  source  of  an  intemipt. 

Flip  Byte  Elects  whether  the  bits  in  the  device  status 

register  indicate  active  when  set  or  active 
when  cleared.  If  a  bit  in  the  flip  byte  is  set, 
it  indieaties  that  the  task  is  active  whenever 
the  coWi^onding  bit  in  the  status  register 
is  clear. 
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Mask  Byte  Selects  one  or  more  interrupt  request  flag 

bits  within  the  device  status  register.  The 
bits  identify  the  active  task  or  device. 

Service  Points  to  the  interrupt  service  routine  for 

Routine  Address    the  device.  You  supply  this  address. 

Static  Points  to  the  permanent  storage  area 

Storage  Address    required  by  the  device  service  routine.  Yon 

supply  this  address. 

Priority  Sets  the  order  in  which  the  devices  are 

polled  (a  number  from  0  to  255). 

Polling  the  Entries.  When  an  IRQ  interrupt  occurs,  OS-9 

enters  the  polling  system  via  the  corresponding  RAM  interrupt 
vector.  It  starts  polling  the  devices  in  order  of  priority.  OS-9 
loads  the  status  register  address  of  each  entry  into  Accumulator 
A,  xi^g  the  device  address  irom  the  table. 

OS-9  performs  U  exclusive-OR  operation  using  the  flip  byte,  fol- 
lowed by  a  logical- AND  operation  using  the  mask  byte.  If  the 
result  is  non-zero,  OS-9  assumes  that  the  device  is  the  source  of 
the  interrupt. 

OS-9  reads  the  device  memory  address  and  service  routine 
address  from  the  table,  and  performs  the  interrupt  service 

Note:  If  you  are  writing  your  own  device  driver,  terminate 
the  interrupt  service  routine  with  an  RTS  instruction,  not 
an  RTI  instruction. 

Adding  Entries  to  the  Table.  You  can  make  entries  to  the  IRQ 
(interrupt  request)  polling  table  by  using  the  Set  IRQ  system 
call  (F$IRQ).  §et  IRQ  is  a  prhil^ed  sys^  mil,  can 
cute  it  only  in  the  system  mode.  OS-9  is  in  system  mode  when- 
ever it  is  running  a  device  driver. 

Note:  The  code  for  the  interrupt  polling  system  is  located 
in  the  1/0  Manager  module.  The  0S9P1  and  OS9P2  mod- 
ules contain  the  physical  interrupt  processing  routines. 
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Virtual  Interrupt  Processing 

A  virtual  IRQ,  or  VIRQ,  is  useful  with  d^ces  in  Multi-Pak 

expansion  slots.  Because  of  the  absence  of  an  IRQ  line  from  the 
Multi-Pak  interface,  these  devices  cannot  initiate  physical  inter- 
rupts. VIRQ  enables  these  devices  to  act  as  if  they  were  inter- 
rupt driven.  Use  VIRQ  only  with  device  driver  and  pseudo  device 
driver  modules.  "VIRQ  is  handled  in  the  Clock  module,  which 
handles  the  VIRQ  polling  table  and  installs  the  F$VIRQ  system 
call.  Since  the  F$VIRQ  system  call  is  dependent  on  clock  initial- 
ization, the  CCSGrO  module  forces  the  clock  to  start. 

The  virtual  interrupt  is  set  up  so  that  a  device  can  be  inter- 
rupted at  a  givKi  number  of  clock  ticks.  The  interrupt  can  occ\ir 
one  %ms,  or  can  be  repeated  as  tag  as  the  difvi^  is  Used. 

The  FfVIRQ  system  call  installs  VIRQ  in  a  table.  This  call 
requires  specification  of  a  5-byte  packet  for  use  in  the  VIRQ 
table.  This  packet  contains: 

•  Bytes  for  an  actual  counter 

•  A  reset  value  for  the  counter 

•  A  status  byte  that  indicates  whether  a  virtual  interrupt 
has  occurred  and  whether  the  VIRQ  is  to  be  re-installed 

in  the  table  aft^r  being  issued 

F$VIRQ  also  specifies  an  initial  tick  count  for  the  interrupt. 
The  actual  call  is  summarized  here  and  it  described  in  detail  in 
Chapter  8. 

Call:  0S9  F$VIRQ 

Input:  (Y)  =  address  of  5-byte  packet 

(X)  =  0  to  delete  entry,  1  to  install  entry 

(D)  =  initial  count  value 

Output:  none 

(CC)  carry  set  m.  error 
(IS)  appropriate  error  code 

The  S-bjrte  packet  is  defined  as  fellows: 

Name  Offset  Function  

Vi.Cnt  $0       Actual  counter 

Vi.Rst  $2       Iteset  value  for  counter 

Vi.Stat  $4       Status  byte 
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Two  of  the  bits  in  the  status  byte  are  used.  These  are: 

Bit  0  -  set  if  VIRQ  occurs 

Bit  7  -  set  if  a  count  reset  is  required 

When  making  an  F$VIRQ  call,  the  packet  might  require  initial- 
izatitm  with  a  reset  value.  Bit  7  of  the  status  byte  must  be 

either  set  or  cleared  to  signify  a  reset  of  the  counter  or  a  one- 
time VIRQ  call.  The  reset  value  does  not  need  to  be  the  same  as 
the  initial  counter  value.  When  OS-9  processes  the  call,  it  writes 
the  packet  address  into  the  VIRQ  table. 

At  each  clock  tick,  OS-9  scans  the  VIRQ  table  and  subtracts  one 
from  each  timer  value.  When  a  timer  coimt  reaches  zero,  OS-9 
performs  the  Mbwing  actions: 

1.  Sets  Bit  0  in  the  status  byte.  This  specifies  a  Virtual  IRQ. 

2.  Checks  Bit  7  of  the  status  hy^  he  a  count  reset  request. 

3.  If  bit  7  is  set,  resets  the  count  using  the  reset  value.  If  bit  7 
is  reset,  deletes  the  packet  address  from  the  VIRQ  table. 

When  a  counter  reaches  zero  and  makes  a  virtual  interrupt 
request,  OS-9  runs  the  standard  interrupt  polling  routine  and 
services  the  interrupt.  Because  of  this,  you  must  install  entries 
on  both  the  VlBjQ  aai  DIBQ  polling  talte  wheneiveP  you  are 
using  a  VIRQ. 

Unless  the  device  has  an  actual  physical  interrupt,  install  the 
device  on  the  IRQ  polling  table  via  the  F$IRQ  system  call  before 
iflsuciz^  it  on  the  VIRQ  table. 

If  the  device  has  a  physical  interrupt,  use  the  interrupt's  hard- 
ware register  address  as  the  polling  address  for  the  F$IRQ  call. 
After  setting  the  polling  aifeeis,  set  the  flip  aai  mask  bytes  for 
&mmi  and        tl:^  lltlEQ  call. 

If  the  device  is  totally  VIRQ-driven,  and  has  no  interrupts,  use 
the  status  byte  from  the  VIRQ  packet  as  the  status  byte.  Use  a 
mask  byte  of  %00000001,  defined  as  Vi.IFlag  in  the  defs  file. 
Use  a  flip  byte  value  of  0.  The  following  examples  show  how  to 
set  up  both  types  of  VIRQ  calls.  The  flifst  example  is  taken  from 
an  ACIA-type  driver  that  has  a  physical  interrupt  found  in  a 
status  register,  but  that  cannot  be  accessed  by  the  processor  if 
used  in  the  Multi-Pak.  The  second  example  is  for  a  device  with 
no  physical  interrupt  handling,  all  interrupts  are  handled 
through  the  VIRQ. 
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VIRQ  Example  i\  -  Device  Driver  possessing  real  IRQ's 

•  Copyright  1385,1986  by  Micfowire  Sysfeis 

•  Corporation,  Reprodueed  Unier  Ueensa 

use  defsfile 

•  actual  mask  byte  for  hardware  interrupt 
IRQReq  set  118888088  Interrupt  Request 


•  offset  to  the  actual  hardware  status  register 

Status  equ  1 

•  VIRQ  countdown  value 

VIRIICNT  e()u  1       do  the  VIRA  on  every  tick 


»  Static  storage  offsets 
org  V.SCF  room  for  scf  variables 


VlRflfiUF  rtnb  5  buffer  for  fate  interrupt  from  Choi! 


NEfl  equ  .  Total  static  stora|e  requireuent 


•  Module  Header 

mod  MEND,NflM,DRIVR*QBJeT,REENW ,ENT,MEM 
fob  UPDAT. 

fsfeidltion  Current  Revision 

«  Driver  entry  jump  table 

ENT  Ibra  INIT 
Ibra  READ 
Ibra  WRITE 
Ibra  GETSTfl 
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Ibra  PUTSTA 
bra  TRMNAT 

•  Actual  mask  information  for  F$1RQ  call  for  the 

•  hardware  interrupt  MASK  fcb  8  no  flip  bits 

•  fcb  IRQReg  Irq  polling  mask 
»  fcb  \l  (higher)  priority 

«<< 4 <<«« t «»»»»» « 

«  tnit 

•  Initialize  the  device 

»  Includes  setting  up  the  IRQ  and  VIRQ  entries 
« 

I  N  IT 


•  Install  IRQ  polling  Table  Entry  first 

•  Use  the  hardware  status  register  and  the  hardware 

*  mast 

Idd  V,PDRT,U  get  port  address  in  D 

add  'Status  point  to  hardware  status  byte 

leax  MA5K,PCR  get  the  hardware  interrupt  mask 

leay  M169,,PC£  tddress  of  interrupt  service  routine 

DS9  nm  ftdd  to  IRQ  polling  table 

bcs  INIT9  error  -  returii  it 

♦  Install  VIRQ  in  Clock  Module  second 
« 

leay  VIRQBUF,U  get  the  5  byte  VIRQ  buffer  pointer 

Ida  HSi  get  reset  flag  for  repeated  VIRQ'S 

sta  Vi,Stat,y  put  it  into  buffer 

Idd  #VIRQCNT  get  count  for  number  of  ticks  for  the,  VIRQ 

std  Vi.Rst.y  put  in  initial  reset  value 

Idx  *1  put  onto  table 

os9  F$VIRQ  make  the  service  request 

bc5  1N1T9  Error  -  return  it 


I  NITS  rts 
REAl 
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WRITE 

GETSTA 

PUTSTft 


•  Subroutine  TRMNflT 

•  Terminata  device,  including  removal  from  tables 

TRMNflT 


•  remove  from  VIR9  table  first 

Idx  *B  remove  from  VIRQ  table 

leay  VIRQBUF.U  get  address 

039  FtVIIQ  remove  modem  from  VIRQ  table 

•  neJiti  remove  from  IRQ  table 
Itfx  #0 

DS9  F$IRQ  remove  modem  from  polling  tbl 
rts 

«  «  «  «  *  «  f  «  «  »*  i 

«  MIRQ 

•  process  Interrupt 

MD.IRQ: 


<  actual  interrupt  service  routine  > 
rts 

emod  Module  Crc 
MEND  equ  ♦ 


•  VtRQ  Example  '2  -  Device  Driver  without  hardware  interrupts 

tin  •«  Ml  ♦»;»:«»»■» 

•  STATIC  8TDRA5E  DEFINITION 
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VIRQBF  Put)  S  luffep  fflf  Mm 
DMEM  equ  . 

«  Mfliule  Header 
• 

mod  DEND,DNAM,DR1VR*0BJC;T,IEENT*REV,DENT,PMEM 
fcb  UPDftT,  mode  byte 

fcb  3  EDITIDN  BYTE 


»  Driver  entry  table 
DENT  Ibra  INIT  initialize 

Ibra  READ 

ibra  WRITE 

Ibra  SETSTflT  get  status 

Ibra  SETSTflT  set  status 
Ibra  TERM  terminate 

•  Mask  information  packet  for  FJIRfl  call 

•  NOTE;  uses  the  virtual  interrupt  flag,  Vi.IFlag,  for 
»  the  maskbyte 

» 

DPtSI  fob  I  TO  flip  bf ts 
fcb  Vi.IFlag  polling  mask  for  VIRS 
fcb  \i  priority 

»»»»«.•«§»:«»♦»».» 

»  INlTIflLIZE  STDiflGE  AND  CONTROLLER 

»  Includes  setting  up  the  IRQ  and  VIRQ  table  entries 

* 

INIT 

•  set  up  IRQ  taMe  entry  f  irst 

•  NOTE;  uses  the  status  register  of  the  VIRQ  buffer  for 

•  the  interrupt  status  register  since  no  hardware  status 

•  register  is  available 
» 

leay  Jlat,ff  get  adi* iSt     status  byte 
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tfr  y,d  put  it  into  D  reg 

leay  DIRQ.PCR  get  address  of  interrupt  routine 

leax  DMSK.PCR  get  VIRQ  mask  info 

os9  F$1RQ  install  onto  table 

bcs  INIT9  exit  on  error 

•  now  set  up  the  VIRQ  table  entry 
leay  VIRQIFjU  point  to  tKe  5-byte  packtt 
Ida       get  tto  reset  flap  to  repeat  VIRS's 

sta  Wl.ilat.y  save  if  In  ttie  buffer 

Idd  iWRflCNT  get  the  VIRQ  counter  value 

std  tfi.,B^t,y  save  it  in  the  reset  area  of  buffer 

tdx  t1  code  to  Install  tite  VIRQ 

059  F$VIRQ  install  on  the  table 

bcs  !NIT9  exit  on  error 


INIT9  rts 


READ 
WRITE 
GETSTflT 
PUTSTAT 

1 1 « 1 1  f  1 1 « f  t  >  * » 1 1  f  f  • « » I 

•  TERM  -  terminate  the  device  and  remove  entries  from 

•  tables 
TERM 

•  remove  from  VIRQ  table  first 

Idx  It  get  zero  to  remove  from  table 
leay  VIRQBF.IJ  get  address  of  packet 
os9  F$VIRQ 

•  then  remove  from  IRQ  table 

Idx  tl  get  zero  to  remove  from  table 
os9  FtIRS 


rts 
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♦  DIRQ  -  interrupt  service  routine 

»  NOTE:  The  service  routine  must  be  sure  to  reset  the 

•  status  byte  Of  the  Villi  picUt  so  that  the  interrupt 
»  looks  at  if  rt  Is  clearei. 

< 

DIRQ 


Ida  VIRQBF»Vi.Stat,U  get  status  byte 
anda  #$FF-Vi , IFlag  mast  off  interrupt  bit 
sta  VIRQBF'Vi.Stat.U  put  it  back 

rts 
EHDD 

DEHD  equ  • 
END 
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In  Chapter  2,  you  learned  that  OS-9  is  based  on  the  concept  that 
memory  is  modular.  This  means  that  each  program  is  considered 
to  be  an  individually  named  object. 

You  also  learned  that  each  program  loaded  into  memory  must  be 
in  the  module  format.  This  format  lets  OS-9  manage  the  logical 
contents  of  memory,  as  well  as  the  physical  contents.  Module 
types  and  formats  are  discussed  in  detail  in  this  chapter. 

Module  Typies 

There  are  several  types  of  modules.  Each  has  a  different  use  and 
function.  These  are  the  main  requirements  of  a  module: 

•  It  cannot  modify  itself. 

•  It  must  be  position-independent  so  that  OS-9  can  load  or 
relocate  it  wherever  space  is  available.  In  this  respect, 
the  module  format  is  the  OS-9  equivalent  of  load  records 
used  in  older  operating  systems. 

A  module  need  not  be  a  complete  program  or  even  6809  machine 
language.  It  can  c^taM  B4SI009  I-code,  constants,  single  sub- 
routines, and  subroutine  packages. 

Module  Format 

Each  module  has  three  parts:  a  module  header,  a  module  body, 
and  a  cyclic-redundaney-check  value  (CRC  ^^lue). 
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Module  Header 


Program 
or 

Constants 


CRC  Value 


Figure  3.1 


Module  Header 

At  the  beginning  of  the  module  (the  lowest  address)  is  the  mod- 
ule header.  Its  form  depends  upon  the  module's  use. 

The  header  contains  information  about  the  module  and  its  use. 
This  information  includes  the  following: 

•  Size 

•  Type  (machine  code,  BAilOOf  ^HUpffad  eode,  and  so  aa) 

•  Attributes  (executable,  re-entrant,  smS.  SO  on) 

•  Data  storage  memory  requirements 

•  Execution  starting  address 

Usually,  you  do  not  need  to  write  routines  to  generate  the  mod- 
ules and  headers.  All  OS-9  programming  languages  automati- 
cally create  modules  and  headers. 

The  module  body  contains  the  program  or  eonstants.  It  usually 
is  pure  code.  The  module  name  string  is  included  in  this  area. 
Figure  3.2  provides  the  offset  values  for  calculating  the  location 
of  a  module's  name.  (See  "Offset  to  Module  Name".) 

CRC  Valiie 

The  last  three  bytes  of  the  module  are  the  Cyclic  Redundancy 
Check  (CRC)  value.  The  CRC  value  is  used  to  verify  the  integ- 
rity of  a  module. 
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When  the  system  first  loads  the  module  into  memory,  it  per- 
tems  a  25-bit  CRC  over  the  entire  modi;&,  iemn  the  firat  hyte  £sf 
the  module  header  to  the  byte  immediatdy  bdfore  the  CRG.  The 

CRC  polynomial  used  is  $800FE3. 

As  with  the  header,  you  usually  don't  need  to  write  routines  to 
generate  the  CRC  value.  Most  OS-9  programs  do  this 
automatically. 

Module  Headers:  Standard  InfomaMon 

The  first  xi^  %tes  of  all  module  h^u3^  me  iefined  as  felkfws; 
Relative 

Address  Use  

$00,$01  Sync  bytes  ($87,$CD) 

$02,$03  Module  size 

$04,$05  Offset  to  module  name 

$06  Module  type/Language 

$07  Attributes/Revision  level 

$08  Header  check 


The  sync  bytes  specify  th&  location  of  the  module.  (The  first  sync 
byte  is  the  start  of  the  fiaodule.)  These  two  bytes  are  constant. 

Module  Size 

The  module  size  specifies  the  size  of  the  module  in  bytes 
(includes  CRC). 

Offset  to  Module  Namm 

The  offeet  to  module  name  specifies  the  address  of  the  ttiodulle 

name  string  relative  to  the  start  of  the  module.  The  name  string 
can  be  located  anywhere  in  the  module.  It  consists  of  a  string  of 
ASCII  characters  with  the  most  significant  bit  set  on  the  last 
character. 


Figure  3.2 
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Type/Language  Byte 

The  type/language  b3^e  specifies  the  type  and  language  of  the 
module. 

The  fmr  most  significant  bits  of  this  bjrte  indicate  the  type. 
Eight  types  are  pre-defined.  Some  of  these  are  for  OS-9's  inter- 
nal use  only.  The  type  codes  are  given  here  (0  is  not  a  legal  type 
code): 


Code 

Module  Type 

Name 

$lx 

Program  module 

Prgrm 

$2x 

Subroutine  module 

Sbrtn 

$3x 

Multi-module  (for  future  use) 

Multi 

$4x 

Data  module 

Data 

$5x-$Bx 

User-definable  module 

$Cx 

OS-9  system  module 

Systm 

$Dx 

OS-9  file  manager  module 

FlMgr 

C^i  ^g?iee  ddver  laadule 

XMm 

$Fx 

OS-9  device  descriptor  module 

Devic 

The  four  least  significant  bits  of  Byte  6  indicate  the  language 
(denoted  by  x  in  the  previous  Figure).  The  language  codes  are 
given  here: 


Code  Laiigixage  

$xO  Data  (non-executable) 

$xl  6809  object  code 

$x2  BASIC09  I-code 

$x3  PASCAL  P-code 

$x4-$xF  Reserved  for  future  use 


Figure  3.4 

By  checking  the  language  type,  high-level  language  runtime 
systems  can  verify  that  a  module  is  the  correct  type  before 
attempting  execution.  BASIC09,  for  example,  can  run  either  I- 
code  or  6809  machine  language  procedures  arbitrarily  by  check- 
ing the  language  type  code. 

Attributes/Revision  Level  Byte 

The  attributeS!*revislsQ  Imd  %te  daBHes  Hie  attrikifces  and  revi- 
sion level  of  the  module. 
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The  four  most  significant  bits  of  this  hyte  are  reserved  for  mod- 
ule attributes.  Currently,  only  Bit  7  is  defined.  When  set,  it  indi- 
cates the  module  is  re-entrant  and,  therefore,  shareable. 

The  four  least  significant  bits  of  this  byte  are  a  revision  level  in 
the  range  0  to  15.  If  two  or  more  modules  have  the  same  name, 
type,  language,  and  so  on,  OS-9  keeps  in  the  module  directory 
only  the  module  having  the  highest  revision  level.  Therefore,  you 
can  replace  or  patch  a  ROM  module,  simply  by  loading  a  new, 
equivalent  module  that  has  a  higher  revision  level. 

Note:  A  previously  linked  module  cannot  be  replaced  until 
its  link  count  goes  to  zero. 

Header  Clie  ck 

The  header  cheek  l^te  c«aitaiiis  the  tm^u  complement  of  the 
Exclusive-OR  of  the  previous  eight  bytes. 

Module  Headers:  Type-Dependent 
Information 

More  information  usually  follows  the  first  nine  bytes  of  a  module 
header.  The  layout  and  meaning  vary,  depending  on  the  module 
type. 

Module  types  $Cx-$Fx  (system  module,  file  manager  module, 
device  driver  module,  and  device  descriptor  module)  are  used 
only  by  OS-9.  Their  formats  are  given  later  in  the  manual. 

Module  types  Six  through  $Bx  have  a  general-purpose  executa- 
ble format.  This  format  is  often  used  in  programs  called  by 
F$Fork  or  F$Chain.  Here  is  the  format  used  by  these  module 
types: 
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Executable  Memory  Module  Format 
Use 


Relathre 
Address 


Check 
Range 


$00 
$01 
$02 
$03 

$04 

$05 

$06 

$07 

$08 

$09 

$0A 

$0B 

$0C 

$0D 


—  Bytes  C$8T,|CD)  — 


—        Module  Size  (bjrtes)  — 


—       Module  Name  Offset  — 


Type 

Laofuage 

Attributes 

Revision 

Head^  Parity  Check 


— ■         Execution  Offset  — 


—     Permanent  Storage  Size 


(Additional  optional  header 

extensions) 


Module  Body 
object  code,  constants, 
and  80  on 


header 
pariiy 


module 
CRC 


CRC  Check  Value 


Figure  3.5 
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As  you  can  see  from  the  preceding  chart,  the  ejcecutable  memory 
has  four  extra  bytes  in  its  header.  They  are: 

$09,$0A  Execution  offset 

$OB,$OC         P^manent  storage  size 

Execution  Offset.  The  program  or  subroutine's  offset  starting 
address,  relative  to  the  first  byte  of  the  sync  code.  A  module  that 
has  multiple  entry  points  (such  as  cold  start  and  warm  start) 
might  have  a  branch  table  starting  at  this  address. 

Permanent  Storage  Size.  The  minimum  number  of  bytes  of 
data  storage  required  to  run.  Fork  and  Chain  use  this  number 
to  allocate  a  process's  data  area. 

If  the  module  is  not  directly  executed  by  a  Fork  or  Chain  system 
call  (for  instance  a  subroutine  package),  this  entry  is  not  used  by 
0§-9.  It  is  commonly  used  to  specify  the  maxlhium  stack  size 
required  by  re-entrant  subroutine  modules.  The  calling  program 
can  check  this  value  to  determine  if  the  subroutine  has  enough 
stack  space. 

When  OS-9  starts  after  a  single  system  reset,  it  searches  the 
entire  memory  space  for  ROM  modules.  It  finds  them  by  looking 
for  the  module  header  sync  code  ($87,$CD). 

When  OS-9  detects  the  header  sync  code,  it  checks  to  see  if  the 
header  is  correct.  If  it  is,  the  system  obtains  the  module  size 
from  the  header  and  performs  a  24-bit  CRC  over  the  entire  mod- 
ule. If  the  CRC  matches,  OS-9  considers  the  module  to  be  valid 
and  enters  it  into  the  module  directory.  All  ROM  modules  that 
are  present  in  the  system  at  startup  are  automatically  included 
in  the  system  module  directory. 

After  the  module  search,  OS-9  links  to  the  component  modules  it 
found.  This  is  the  secret  to  OS-9's  ability  to  adapt  to  almost  any 
6809  computer.  It  automatically  locates  its  required  mat  opMonitl 
component  modules  and  rebuilds  the  system  ^h  time  it  is 
started. 
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Chapter  4 

OS-9's  Unified 
Input/Output  System 


Chapter  1  mentioned  that  OS-9  has  a  unified  I/O  system,  con- 
sisting of  all  modules  except  those  on  the  kernel  level.  This  chap- 
ter discusses  the  I/O  modiiles  in  detail. 


I/O  System  Modules 


INIT 

OS-9  KERNEL 
(0S9P1 ,  0S9P2) 

Clock 

Ram 

CC3Disk 

CCSHdisk 

Pipe 

ACIAPak 

ModPak 

CC3iO 

Ram  Disk 

Disk 

Disk 

Driver 

Driver 

Driver 

Driver 

Driver 

Driver 

(Piper) 

RO 


DO     DD  D1 


HO 


RBF  Device  Deseriptors 


Pipe 


M1 


T2 


M2  T3 


Pipe  Descr,     SCf  Device  Descriptors 


Vdgint 
CC3iO 
Interfeoe 


Term_Vdg 
Oesc 


Grfint 
GC3I0 
Interface 


Windint 
CC3I0 
IrrterfacB 


GrfDrv 


Term.Win 
Desc 

w 

W1 

W2 
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The  VDG  Interface  performs  both  interface  and  low  level  routines 
for  VDG  Color  Computer  2  compatible  modes  and  has  limited 
support  for  high  res  screen  allocation. 

The  Grfint  Interface  provides  the  standard  code  InterfH-eiiMons 
and  interface  functions. 

The  Windint  Interface,  available  in  the  Multi-view  package,  con- 
tains all  the  functionality  of  GrfInt,  along  with  additional  sup- 
port features.  If  you  use  Windint,  do  not  include  Grfint. 

Both  Windint  and  GrfInt  use  the  low-level  driver  GrfDrv  to  per- 
form drawing  on  the  bit-map  screens. 

Term_VDG  uses  CCSIO/VdgInt  while  Term_win  and  all  win- 
dow descriptors  use  CC3I0/(WindInt/Gr£[nt)/GrfDrv  modules. 

The  I/O  system  provides  system-wide,  hardware-independent  I/O 
services  for  wea:  programs  and  OS-9  itself.  All  I/O  system  calls 
are  received  hy  the  kernel  and  passed  to  the  I/O  manager  for 

processing. 

The  I/O  manager  performs  some  processing,  such  as  the  alloca- 
tion of  data  structures  for  the  I/O  path.  Then,  it  calls  the  file 
managers  and  device  drivers  to  do  most  of  the  work.  Additional 
file  manager,  device  driver,  and  device  descriptor  modules  can  be 
loaded  into  memory  from  files  and  used  while  the  system  is 
running. 

The  I/O  Manager 

The  I/O  manager  provides  the  fegfc  level  of  service  of  I/O  system 
calls.  It  routes  data  on  I/O  process  paths  to  and  from  the  appro- 
priate file  managers  and  device  drivers. 

The  I/O  Manager  also  malntaiai  two  importsffiit  int»aal  G^-i' 
data  structures — the  device  table  and  the  path  table.  Never  mod- 
ify the  I/O  manager. 

When  a  path  is  opened,  the  I/O  manager  tries  to  link  to  a  mem- 
ory module  that  has  the  device  name  given  or  implied  in  the 
pathlist.  This  module  is  the  device  descriptor.  It  contains  the 
names  of  the  device  driver  and  file  manager  for  the  device.  The 
I/O  manager  saves  the  names  so  later  system  calls  can  be  routed 
to  these  modules. 
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File  Managers 

OS-9  can  have  any  number  of  file  manager  modules.  Each  of 
these  modules  processes  the  raw  data  stream  to  or  from  a  class 
of  device  drivars  that  have  similar  operational  characteristics.  It 
removes  as  many  unique  characteristics  as  possible  from  I/Q 
operations.  Thus,  it  assures  that  similar  devices  conform  to  the 
OS-9  standard  I/O  and  file  structure. 

The  file  manager  also  is  responsible  for  mass  storage  allocation 
and  directory  processing,  if  these  are  applicable  to  the  class  of 
devices  it  serves. 

File  managers  usually  buffer  the  data  stream  and  issue  requests 
to  the  kernel  for  dynamic  allocation  of  buffer  memory.  They  can 
also  monitor  and  process  the  data  stream,  for  example,  adding 
line-feed  characters  a£t&c  carriage-return  characters. 

The  file  managers  are  re-entrant.  The  three  standard  OS-9  file 

managers  are: 

•  Random  block  file  manager:  The  RBF  manager  supports 
random-access,  block-structured  devices  such  as  didc  sys- 
tems and  bubble  memories.  (Chapter  5  discusses  the 

RBF  manager  in  detail.) 

•  Sequential  Character  File  Manager:  The  SCF  manager 
supports  single-character-oriented  devices,  such  as  CRTs 
or  hardcopy  terminals,  printers,  and  modems.  (Chapter  6 
discusses  SCF  in  detail.) 

•  Pipe  File  Manager  (PIPEMAN):  The  pipe  jnmm^w  sup- 
ports  interprocess  communication  via  pipes. 

File  Manager  Structure 

Every  file  manager  must  have  a  branch  table  in  exactly  the  fol- 
lowing format.  Routines  that  are  not  used  by  the  file  manager 
EQWst  branch  to  an  error  routine,  that  sets  the  ceirry  and  loads 
Regisfter  B  with  aa  apprcptiate  ^ror  mdm  h^m  mimnstag.  Bou- 
tines  returning  without  error  must  ensure  that  the  carry  bit  is 
clear. 
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*  All   routines  are  entered  with: 

»   (Y)   =  Path  Descriptor  pointer 

»  (U)  =  Caller's  regiatep  stack  pointer 

EntryPt    equ  » 

Ibra  Create 

Ibra  Open 

Ibra  MakDir 

Ibra  ChgDir 

Ibra  Delete 

Ibra  Seek 

Ibra  Read 

ibra  Nrite 

Ibra  ReadLn 

Ibra  WriteLn 

Ibra  GetStat 

Ibra  PutStat 

Ibra  Close 

Create,  Open 

Create  and  Open  handle  file  creating  and  opening  for  devices. 
Typically,  the  process  involves  allocating  any  required  buffers, 
initializing  path  descriptor  variables,  and  establishing  the  path 
name.  If  the  file  manager  controls  multi-file  devices  (RBF), 
directory  searching  is  performed  to  find  or  create  the  specified 
file. 

Makdir 

MaMll?  creates  a  directory  file  on  milti-file  devfees.  Mkkdfr  is 
neither  preceded  by  a  Create  nor  followed  by  a  Close.  File  man- 
agers that  are  incapable  of  supporting  directories  need  to  return 
carry  set  with  an  appropriate  error  code  in  Register  B. 

ChgDir 

On  multi-file  devices,  ChgDir  searches  for  a  directory  file.  If 
ChgDir  finds  the  directory,  it  saves  the  address  of  the  directory 
(up  to  four  bytes)  in  the  caller's  process  descriptor.  The  descrip- 
tor is  located  at  P$DI0  +  2  (for  a  data  directory)  or  P$DI0  +  8 
(for  an  execution  directory). 
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In.  the  <s8se  of  the  RBF  manager,  the  address  of  the  directory's 
file  descriptor  is  saved.  Open/Create  begins  searching  in  the  cur- 
rent directory  when  the  caller's  pathlist  does  not  begin  with  a 
slash  (/).  File  managers  that  do  not  support  directories  should 
return  the  carry  set  and  an  a^(piate  error  code  in  Register 
B. 

Delete 

Multi-file  device  managers  handle  file  delete  requests  by  initiat- 
ing a  directory  search  that  is  similar  to  Open.  Once  a  device 
manager  finds  the  file,  it  removes  the  file  from  the  directory. 
Any  media  in  use  by  the  file  are  returned  to  tilm^d  status.  In 
the  case  of  the  RBF  manager,  space  is  returned  for  system  use 
and  is  marked  as  available  in  the  free  cluster  bit  map  on  the 
disk.  File  managers  that  do  not  support  multi-  file  devices 
return  an  error. 

Seek 

File  managers  that  support  random  access  devices  use  Seek  to 
position  file  pointers  of  an  already  open  path  to  the  byte  speci- 
fied. Typically,  the  positioning  is  a  logical  movement.  No  error  is 
produced  at  the  time  of  the  seek  if  the  position  is  bejwnd  the 
current  "end  of  file". 

Normally,  file  managers  that  do  not  support  random  access 
ignore  Seek.  Hmever,  an  SCF-tjrpe  manager  can  use  Seek  to 
p@-fi)rm  cursor  positioning. 

Read 

Read  returns  the  number  of  bytes  requested  to  the  user's  data 
baffi*.  Make  siire  Resul  returns  an  EOF  eiror  if  there  is  no  data 

available.  Read  must  be  capable  of  copying  pure  binary  data,  and 
generally  performs  no  editing  on  the  data.  Generally,  the  file 
manager  calls  the  device  driver  to  actually  read  the  data  into 
the  buffer.  Then,  the  file  manager  copies  the  data  from  the  buffer 
into  the  user's  data  area  to  keep  file  mana^rs  def  ice- 
independent. 
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Write 

The  Write  request,  like  Read,  must  be  capable  of  recording  pure 
binary  data  without  alteration.  The  routines  for  Bead  and  Write 

are  almost  identical  with  the  exception  that  Write  uses  the 
device  driver's  output  routine  instead  of  the  input  routine.  The 
RBF  manager  and  similar  random  access  devices  that  use  fixed- 
length  records  (sectors)  must  often  preread  a  sector  before  writ- 
ing it,  unless  they  are  writing  the  entire  sector.  In  OS-9,  writing 
past  the  end  of  file  on  a  (tevice  expands  the  file  with  new  data. 

ReadLn 

ReadLn  differs  from  Read  in  two  respects.  First,  ReadLn  termi- 
nates  "s^eti  the  first  end-of-line  fearriage  rettttti)  is  eftcountered. 
ReadLn  performs  any  input  editing  that  is  appropriate  for  the 
device.  In  the  case  of  SCF,  editing  involves  handling  functions 
such  as  backspace,  line  deletion,  and  the  reEtnoval  of  the  high- 
order  bit  from  characters. 

WriteLn  is  the  counterpart  of  ReadLn.  It  calls  the  device  driver 
to  transfer  data  up  to  and  including  the  first  (if  any)  carriage 
return  encountered.  Appropriate  output  editing  can  also  be  per- 
formed. For  example,  SCF  outputs  a  line  feed,  a  carriage  return 
character,  and  nulls  (if  appropriate  for  the  device).  It  also  pauses 
at  the  end  of  a  screen  page. 

GetStat,  PutStat 

The  GetStat  (get  status)  and  PutStat  (put  status)  system  calls 
are  wildcard  calls  designed  to  provide  a  method  of  accessing  fea- 
tures of  a  device  Cor  file  manager)  that  are  not  generally  device 
independent.  The  file  manager  can  perform  specific  functions 
such  as  setting  the  size  of  a  file  to  a  given  value.  Pass  unknown 
status  calls  to  the  driver  to  provide  further  means  of  device  inde- 
pendence. For  example,  a  PutStat  call  to  format  a  disk  track 
imght  behave  differentiiy  on  different  tj^es  of  disk  controllers. 
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Close 


Close  is  responsible  for  ensuring  that  any  output  to  a  device  is 
completed.  (If  necessary,  Close  writes  out  the  last  buffer.)  It 
releases  any  buffer  space  allocated  in  an  Open  or  Create.  Close 
does  not  execute  the  device  driver's  tearaunate  routine,  but  can, 
do  specific  end-df-file  pressing  if  you  wasit  it  to,  such  as  "writ- 
ing end-of-file  records  on  disks,  or  form  feeds  on  printers. 

Interfacing  with  Device  Drivers 

Strictly  speaking,  device  drivers  must  conform  to  the  general  for- 
mat presented  in  this  manual.  The  I/O  Manager  is  slightly  dif- 
ferent because  it  only  uses  the  Init  and  Terminate  entry  points. 
Other  entry  points  need  only  be  compatible  with  the  file  man- 
ager for  which  the  driver  is  written.  For  example,  the  Read  entry 
point  of  an  SCF  driver  is  expected  to  return  one  byte  from  the 
devise,  'Vhe  B@ffid  pdnt  of  an  drii^,  m  the  other 
tasd,  ei^eA  "Brnt^  to  return  an  en^e  m^m. 


The  following  code  is  part  of  an  SCF  file  manager.  The  code 
shows  how  a  file  manager  might  call  a  driver. 
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« 


lOEXEC 

Execute  Device's  Read/Write  Routine 


« 


Paa^Bied'! 


(X) 
(Y) 
CU) 


Output  charaetef"  Cwrlte) 
Device  Table   entry  ptr 
Path  Descriptor  pointer 
Offset  of  routine  CD*Read, 


* 


D*Write3 

•     Returns:     CA>  =  Input  char  tread) 

»  (B)  =  Error  code,  CC  set   if  error 

»     Destroys  B,CC 

IDEXEC  pshs  a,x,y,u  save  registers 
Idu  V$STAT,x  get   static   storage  for  driver 
Idx  V$DRIV,x  get   driver  module  address 
Idd  M$EXEC,x  and  offset  of  execution  entries 
addd  5,s  offset  by  read/write 
leax  d,x  absolute  entry  address 
Ida    ,5+   restore  char   (for  write) 
jsr   0,x  execute  driver  read/write 
puis  x,y,u,pc  return  (A)=char,  (B)=error 

emod   Module  CRC 
Size  equ   •   size  of   sequential   file  manager 

Device  Driver  Modules 

The  device  driver  modules  are  subroutiae  packages  that  perform 
basic,  low-level  I/O  transfers  to  or  from  a  specific  type  of  I/O 
device  hardware  controller.  These  modules  aeti  re«entarant.  So, 
one  copy  of  the  module  can  concurrently  run  sefveral  devices  that 

use  identical  I/O  controllers. 

Device  driver  modules  use  a  standard  module  header,  in  which 
the  module  type  is  specified  as  code  $Ex  (device  driver).  The  exe- 
cution c&set,  addrtM  in  the  module  header  points  to  a  branch 
taMe  that  has  a  minimum  of  ^  S-brie  enlxiesL 


Each  isntry  is  typically  an  LBRA  to  the  corresponding  subrou- 
tine. The  file  managers  call  specific  routines  in  the  device  driver 
through  this  table,  passing  a  pointer  to  a  path  descriptor  and 
passing  the  hardware  control  register  address  in  the  6809  regis- 
ters. The  branch  table  looks  like  this: 


4-8 


OS-9's  Unified  Inpuf/Ou^ut  ^stem  1 4 


Code  Meaning 


+  $00  Device  initialization  routine 

+  $03  Read  from  device 

+  $06  Write  to  device 

+  $09  Get  device  status 

+  $0C  Set  device  status 

+  $0F  De^^  tersidmtim  i^oatij^ 

(Pbr  a  complete  description  of  the  parameters  passecl  to  these 
subroutines,  see  the  "Device  Driver  Sulsroutines"  sections  in 
Chapters  5  and  6.) 
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Device  Driver  Module  Format 

Use 


Relative 

Address 


Cheek 
Range 


—      Sync  Bytes  ($87,$CD)  — 


—        Module  Size  (bytes)  — 


—       IVfodiile  Name  Offset 


Type 

Lcmguage 

Attributes 

Revision 

Header  Parity  Check 


—         Execution  Offset  — 


—     Permanent  Storage  Size  — 


Mode  Byte 


Parity 


Module 

CRC 


lii&idule  Body 


CRC  Check  Value 


$0D  Mode  Byte  -  (D  S  PE  PW  PR  E  W  R) 
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OS-9  Interaction  With  Devices 

Device  drivers  often  must  wait  for  hardware  to  complete  a  task 
or  for  a  user  to  enter  data.  Such  a  wait  situation  occurs  if  an 
SCF  device  driver  receives  a  Read  but  there  is  no  data  is  avail- 
able, or  if  it  receives  a  Write  and  no  bviffer  space  is  available. 
OS-9  drivers  that  encounter  this  situation  should  suspend  the 
current  process  (via  F$Sleep).  In  this  way  the  driver  allows  other 
processes  to  continue  using  CPU  time. 

The  most  efficient  way  for  a  driver  to  awaken  itself  and  resume 
processing  data  is  by  using  interrupt  requests  (IRQs).  It  is  possi- 
ble for  the  driver  to  sleep  for  a  number  of  system  clock  ticks  and 
then  check  the  device  or  buffer  for  a  ready  signal.  The  drawbacks 
to  this  technique  are: 

•  It  requires  the  system  clock  to  alwsgrs  remain  active. 

•  It  might  require  a  large  number  of  ticks  (perhaps  20)  for 
the  device  to  become  ready.  Such  a  case  leaves  you  with 
a  dilemma.  If  you  make  the  program  sleep  fin*  two  ticks, 

the  system  wastes  CPU  time  while  checking  for  device 
ready.  If  the  driver  sleeps  20  ticks,  it  does  not  have  a 
good  response  time. 

An  interrupt  system  allows  the  hardware  to  report  to  the  CPU 
and  the  device  drivers  when  the  device  is  finished  with  an  opera- 
tion. Using  interrttpts  to  its  adv£tntage,  a  defvice  driver  can  set 
up  interrupt  handling  to  occur  when  a  character  is  sent  or 
received  or  when  a  disk  operation  is  complete.  There  is  a  built-in 
polling  facility  for  pausing  and  awakening  processes.  Here  is  a 
technique  for  handling  interrupts  in  a  device  driver: 

1.  Use  the  Init  routine  to  place  the  driver  interrupt  service  call 
(IRQSVO)  routine  in  the  IRQ  polling  sequence  via  an  F$IRQ 
sy  stem  call: 

Idd   V.PortjU   get    address    to  poll 
leax    IRQPDLL.pcr   point    to    IRQ  packet 
leay   IRQSVC,pcr   point    to    IRQ  routine 
OSS  F$IRQ  add  dev  to  poll  sequenoe 
bos  Error  abnormal  exit   if  error 

2.  Ensure  that  drivesr  programs  "vraitlng  fta*  their  hardware,  call 

the  sleep  routine.  The  sleep  routine  copies  V.Busy  to 
V.Wake.  Then,  it  goes  to  sleep  for  some  period  of  time. 
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3.  When  the  driver  program  wakes  up,  have  it  check  to  see 
whether  it  was  awakened  by  an  interrupt  or  by  a  signal  sent 
frcmi  some  othar  process. 

Usually,  the  driver  performs  this  check  by  reading  the 
V.Wake  storage  byte.  The  V.Busy  byte  is  maintained  by  the 
file  manager  to  be  used  as  the  process  ID  of  the  process 
using  the  driver.  When  V.Busy  is  copied  into  V.Wake,  then 
V.Wake  becomes  a  flag  byte  and  an  information  byte.  A  non- 
zero Wake  byte  indicates  that  there  is  a  process  awaiting  an 
interrupt.  The  value  in  the  Wake  byte  indicates  the  process 
to  be  mmkms4.  %  sliding  a  wakettp  ffi[gnal  as  shown  in  the 
foUowiiig  (x^: 

Ida  V.Bu5y,u  get   proc  ID 

sta  V . Wa k e , a  arrange   for  wakeup 

andcc  #'*IntMaaks         prep  for  interrupts 
SleepBO  Idx  #0  or  any  other  tick  time 

(if  signal  test} 
QS9  F$Sleep  await   an  IRQ 

Idx  D.Proc  get   proc   desc   ptr  if 

S 1 §ne 1  test 
Idb  P$5ignal,x  is  signal  present? 

(if  signal  test) 
bne  SigTest  bra   if  so  if  signal 

test 

tst  V.I4ake,u  IRGi  oceurf 

bne  SleepBO  bra   if  not 

Note  that  the  code  labeled  "if  signal  test"  is  only  necessary 
if  the  driver  wishes  to  return  to  the  caller  if  a  signal  is  sent 
without  waiting  for  the  device  to  finish.  Also  note  that  IRQs 
and  FIRQs  must  be  masked  between  the  time  a  command  is 
given  to  %m  device  and  the  moving  of  V.Busy  and  V.Wake.  If 
th^  are  not  masked,  it  is  possible  for  the  device  IRQ  to 
occur  and  the  IRQSVC  routine  to  become  confused  as  to 
whether  it  is  sending  a  \rakeup  signal  or  not. 
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4.  When  the  device  issues  an  interrupt,  OS-9  calls  the  routine 
at  the  address  given  in  F$IRQ  with  the  interrupts  masked. 
Make  the  routine  as  short  as  possible,  and  have  it  return 
with  an  RTS  instruction.  IRQSVC  can  verify  that  an  inter- 
rupt has  occurred  for  the  device.  It  needs  to  clear  the  inter- 
rupt to  retrieve  any  data  in  the  device.  Tbm  the  Y.Wake 
byte  communicates  with  the  main  driver  module.  If  V.'^ke 
is  non-zero,  clear  it  to  indicate  a  true  device  interrupt  and 
use  its  contents  as  the  process  ID  for  an  F$Send  system  call. 
The  F$Send  call  smds  a  wakeup  sigoal  to  Hm  process.  Here 
is  an  example: 

Idx  V.PortjU   get   device  address 

tst    ??    is    it    real    interrupt   from  device? 

bne    IRQ5VC90   bra   to   error    if  not 

Ida  Data,x  get   data   from  device 

sta  8,y 

Ida  V.Wake,u 

beq    IRQSVC80   bra   if  none 

clr  V.Walce,u  clear  it  as  flag  to  main 

routine 

Idb  #S$Wake,u  get  wakeup  signal 
QS9  F$Send   send   signal    to  driver 
IRQSVC80   clrb   clear   carry  bit    (all    is  well) 
rts 

IRQSVC90   comb   set   carry  bit   Cis  an   IRQ  call) 
rts 

Suspend  State  (Level  Two  only) 

The  Suspend  State  allows  the  elimination  of  the  F$Send  system 
call  during  interrupt  handling.  Because  the  process  is  already  in 
the  active  queue,  it  need  not  be  moved  ttem  one  queue  to 
another.  The  device  driver  IRQSVC  routine  can  now  wake  up  the 
suspended  main  driver  by  clearing  the  process  status  byte  sus- 
pend bit  in  the  process  state.  Ibllowing  are  sample  routines  for 
the  Sleep  and  IRQSVC  calls: 

Ida  D.Proc   get   process  ptr 

sta  V,Wake,u  prep  for  re-awakening 

enable  device  to  IRQ,  give  command,  etc. 

bra  CmdBO  enter  suspend  loop 

Cmd30   Idx  D.Proc  get  ptr  to  process  deso 
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Ida  P$State,x  get  state  flag 

ora  ji'Suspend  put  proc  In  suspend  state 

ata  P$State,x   save   it    in  proc  desc 
andcc  #"IntMask5   unmask  interrupts 
Idx   #1    give  up  time  slice 
□S9  F$Sleep  suspend  (in  active  queue) 

CmdSO  orcc  #Int Masks  mask  interrupts  while 

changing  state 

Idx  D.Proc   get   proc  desc  addr-  Cif  signal 

test) 

Ida  P$Signal,x  get   signal  (if  signal  test) 
beq  SigProc  bra  if  signal  to  fae  handled 

Ida  V . Wa k e  ,  u   true  interrupt? 
bne  Cmd30   bra   if  not 

andcc  **IntMaslcs  assure  interrupts  unmasked 

Note  that  D.Proc  is  a  pointer  to  the  process  descriptor  of  the  cur- 
rent process.  Broeess  descriptors  are  always  allocated  on  256- 
hyte  page  boundaries.  Thus,  having  the  high  order  byte  of  the 
address  is  adequate  to  locate  the  descriptor.  D.Proc  is  put  in 
V.Wake  as  a  dual  value.  In  one  instance,  it  is  a  flag  byte  indi- 
cating that  a  process  is  indeed  suspended.  In  the  other  instance, 
it  is  a  pointer  to  the  process  descriptor  which  enables  the 
IRQSVC  routine  to  clear  the  suspend  bit.  It  is  necessary  to  have 
the  interrupts  masked  from  the  time  the  device  is  enabled  until 
the  suspend  bit  has  been  set.  Making  the  interrupts  ensure  that 
the  IRQSVC  routine  does  not  think  it  has  cleared  the  suspend 
bit  before  it  is  even  set.  If  this  happens,  when  the  bit  is  set  the 
process  might  go  into  permanent  suspension.  The  IRQSVC  rou- 
tine sample  follows: 

Idy  V.Port,u  get   dev  addr 

tst  V.UIake,u  is  process  awaiting 

I RQ? 

beq  ItSSVCER  no  exit 

clear  device  interrupt 

exit   if   IRQ  not  from  this  device 

Ida  V.Wake,u  get   process  ptr 

c  1  r  b 

stb  V.Nake,u  clear  proc  waiting  flag 
tfr  d, X  get  process  descriptor  ptr 
Ida  PtState.x  get  state  flag 
anda  #  Suspend  clear   suspend  state 
sta  P$State,x  save  it 
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clrb  clear  carry  bit 
rts 

IRQSVCER  comb  set  carry  bit 
rts 

Device  J>mci$T^T  Mo&vJm 

Device  descriptor  modules  are  small,  non-executable  modules. 
Each  one  provides  information  that  associates  a  specific  I/O 
device  with  its  logical  name,  hardware  controller  address(es), 
device  driver,  file  manager  name,  and  initialization  parameters. 

Unlike  the  device  drivers  and  file  managers,  which  operate  on 
classes  of  devices,  each  device  descriptor  tailors  its  functions  to  a 
specific  device.  Each  device  must  have  a  device  descriptor. 

Device  descriptor  modules  use  a  standard  module  header,  in 
which  the  module  type  is  specified  as  code  $Fx  (device  descrip- 
tor). The  name  of  the  module  is  the  name  by  which  the  system 
and  user  know  the  device  (the  device  name  given  in  pathlists). 

The  rest  of  the  device  descriptor  header  consists  of  the  infijrma- 
tion  in  the  following  chart: 


Relative 

Address(es)  Use 


$09,$0A 

The  relative  address  of  the  file  manager 
name  string  address 

$OB,$OC 

The  relative  address  of  the  device  driver 

name  string 

$0D 

Mode/Capabilities:  D  S  PE  PW  PR  E  W  R 
(directory,  single  user,  public  execute,  pub- 
lic write,  public  read,  execute,  write,  read) 

$0E,$0F,$10 

The  absolute  physical  (24-bit)  address  of  the 
device  controller 

$11 

The  number  of  bytes  in  hytes)  in  the  ini- 
tialization table 

$12,$12  +  n 

Initialization  table 

When  OS-9  opens  a  path  to  the  device,  the  system  copies  the  ini- 
tialization table  into  the  option  section  (PD.OPT)  of  the  path 
descriptor.  CSee  'Tath  Descriptors"  in  this  chapi^.) 
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The  values  in  this  table  can  be  used  to  define  the  operating 
parameters  that  are  alterable  by  the  Get  Status  and  Set  Status 
system  calls  (I$GetStt  and  I$SetStt).  For  example,  parameters 
tlmt  are  used  when  initializing  terminals  define  which  control 
^wmm^m&  are  to  be  used  for  tenons  such  as  backspaice  and 

The  initialization  table  can  be  a  maximum  of  32  bytes  long.  If 
the  table  is  fewer  than  32  bytes  long,  OS-9  sets  the  remaining 
values  in  the  path  descriptor  to  0. 

You  might  wish  to  add  devices  to  your  system.  If  a  similar  device 
driver  already  easts,  all  you  need  to  do  is  add  the  new  hardware 
and  load  anoither  device  descriptor.  Devise  descriptors  can  be  in 
the  boot  module  or  they  can  be  loaded  into  RAM  from  mass-stor- 
age files  while  the  system  is  running. 

The  following  diagram  illustrates  the  device  descriptor  format: 
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Relative 
Address 


Device  Descriptor  Ibrmat 
Use 


Check 
Range 


—     Sync  Bytes  ($87,$CD)  — 


F$  (Type) 

$1  (Lang) 

Attributes 

Revision 

Module  Size  (bytes) 


Of&et  to  Module  Name  — 


'Bm^  Parity  Check 


Offset  to  File  Manager 
Name  String 


Offset  to  Device  Driver 
Name  String 


Mode  Byte 


Device  Controller 
Absolute  Physical  Addr. 
(24  bit) 


Initialization  Table  Size 


(Initialization  Table) 


header 
parity 


module 
CRC 


(Name  Strings,  and  so  on) 


CRC  Check  Value 
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Pai^  Descriptors 

Every  open  path  is  represented  by  a  data  structure  called  a  path 
descriptor  (PD).  The  PD  contains  the  information  the  file  man- 
agers and  device  drivers  require  to  perform  I/O  functions. 

PDs  are  64  bjrtes  long  and  are  dynamically  allocated  and  d^lla- 
cated  by  the  I/O  manager  as  paths  are  opened  and  closed. 

They  are  internal  data  structures,  that  are  not  normally  refer- 
enced from  user  or  applications  programs.  The  description  of  PDs 
is  presented  here  mainly  for  those  programmers  who  need  to 
write  custom  file  managers,  device  drivers,  or  other  extensions  to 

PDs  have  three  sections.  The  first  section,  which  is  ten  bytes 
long,  is  the  same  for  all  file  managers  and  device  drivers.  The 
information  in  the  first  section  is  shown  in  the  following  chart. 

Path  Descriptor:  Standard  Information 


Name 

Relative 

Size 

1  Use 

PD.PD 

$00 

1 

Path  number 

PD.MOD 

$01 

1 

Access  mode:  1  =  read,  2  = 
write,  3  =  update 

PD.CNT 

$02 

1 

Number  of  open  paths  using 
this  PD 

PD.DEV 

$03 

2 

Address  of  the  associated 
device  table  entry 

PD.CPR 

$05 

1 

Current  process  ID 

PD.RGS 

$06 

2 

Address  of  the  caller's  regis- 
ter B^mh. 

m.mm 

$01 

2 

Addrisss  of  Mm  iSS-byte 
dais  bujfer  (if  wai) 

PD.FST 

mA 

it 

DigSned  lgf  thm  file  manager 

PDOPT 

$20 

32 

Reserved  for  the  Getstat/ 
Setstat  options 

PD.FST  is  22-byte  storage  reserved  for  and  defined  by  each  type 
of  file  maxtager  for  file  pointers,  pemumeM  Vi^al>l@s,  an^  S0  m* 
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PD.OPT  is  a  32-byte  option  area  used  for  file  or  device  operat- 
ing parameters  that  are  dynamically  alterable.  When  the  path  is 
opened,  the  I/O  manager  initializes  these  variables  by  copying 
the  initialization  table  that  is  in  the  device  descriptor  module. 
User  irograms  ean  elim^fe  tites  wbies  late,  ui^iag  'ISm^  Get  Status 
and  Set  Status  system 

PD.FST  and  PD.OPT  are  defined  for  the  file  manager  in  the 
assembly-language  equate  file  (SCFDefs  for  the  SCF  manager  or 
BBFD^s  f(nr  the  RBF  manager). 
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Random  Block  Fila  Manage 


The  random  block  file  manager  (RBF  manager)  supports  disk 
storage.  It  is  a  re-entrant  subroutine  package  called  by  the  I/O 
manager  for  I/O  system  calls  to  random-access  devices.  It  main- 
tains the  logical  and  physical  file  structures. 

During  normal  operation,  the  RBF  manager  requests  allocaibij. 
and  deallocation  of  256-byte  data  buffers.  Usually,  one  buff^  is 
required  ijr  each  opett  file.  When  physical  I/O  ftinctions  are  nec- 
essary, the  RBF  manager  directly  calls  the  subroutines  in  the 
associated  device  drivers.  All  data  transfers  are  performed  using 
256-byte  data  blocks  (pages). 

The  RBF  manager  does  not  deal  directly  with  physical  addresses 
such  as  tracks  and  cylinders.  Instead,  it  passes  to  the  device 
drivers  address  parameters,  using  a  standard  address  called  a 
logical  sector  number,  or  LSN.  LSNs  are  integers  from  0  to  n-1, 
where  n  is  the  maximum  number  of  sectors  on  the  media.  The 
driver  translates  the  logical  sector  number  to  actual  cylinder/ 
track/sector  values. 

Because  the  RBF  manager  supports  many  devices  that  have  dif- 
ferent performance  and  storage  capacities,  it  is  highly  parame- 
ter-driven. The  physical  parameters  it  uses  are  stored  on  the 

media  itself 

On  disk  systems,  the  parameters  are  written  on  the  first  few 
sectors  of  Track  0.  The  device  drivers  also  use  the  information, 
particularly  the  physical  parameters  stored  on  Sector  0.  These 
parameters  are  written  by  the  FORMAT  program  that  initial- 
izes and  tests  the  disk. 

Logical  and  Physical  Disk  Organization 

All  disks  used      OS-9  store  basic  identification,  file  structure, 


LSN  0  is  the  idkniifteation  sector.  LSIf  1  is  the  disk  alhcatkm 

map  sector.  LSN  2  marks  the  beginning  of  the  disk's  ROOT 
directory.  The  following  section  tells  more  about  LSN  0  and  LSN 
1. 
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Identification  Sector  (LSN  0) 


LSN  0  contains  a  description  of  the  physical  and  logical  charac- 
teristics of  ti»  itt.  ebaracteristics  are  set  %  liie  FOR- 
MAT commaxd  frog^axQ  "^hsa  the  disk  is  initialized 

The  following  table  gives  the  OS-9  mnemonic  name,  byte 
address,  size,  and  description  of  each  value  stored  in  this  LSN  0. 

Relative  Size 
Nmne        i^idress  (Bytes)  Use 


ro.TiDT 
DD,TKS 
DD.MAP 

DD.BIT 
DD.DIR 

DD.OWN 

DD-ATT 

DDJ)SK 


$00 

$m 

$04 

$06 
$08 

$0B 
$0D 
$0E 


DD.FMT  $10 

DD.SPT  $11 

DD.RES  $13 
DD.BT 

DD.BSZ  $18 

DD.DAT  $1A 

DD.NAM  $1F 


3 
1 
2 

2 
3 

2 
1 
2 


2 
2 
3 


5 

32 


Numte  cf  sectors  on  disk 

Tvaek      (in  sectors) 

Number  of  bytes  in  the  alloca- 
tion bit  map 

Number  of  sectors  per  cluster 

Starting  sector  of  the  ROOT 
directory 

Owner's  user  number 
Disk  attributes 

Disk  identification  (for  internal 

use) 

Disk  fonnat,  density,  number 


Hombier  of  sectors  per  track 
Bes^ved  for  future  use 
Stiftrting  sector  of  the  boot- 


Size  of  the  bootstrap  file  (in 

bytes) 

Time  of  creation  (Y:M:D:H:M) 

Volume  name  in  which  the  last 
character  has  the  most  signifi- 
cant bit  set 


DD.OPT 


$3F 


Path  descriptor  options 
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Disk  Allocation  Map  Sector  (LSN  1) 

LSN  1  contains  the  disk  allocation  map,  which  is  created  by 
FORMAT.  This  map  shows  which  sectors  are  allocated  to  the 
files  and  which  are  free  for  futxire  use. 

Each  bit  in  the  allocation  map  represents  a  sector  or  cluster  of 
sectCHS  on  the  disk.  If  the  bit  is  set^  the  sector  is  considered  to  be 
in  use,  deifective,  or  non-existent.  If  the  bit  is  cleared,  the  cdire- 
sponding  cluster  is  available.  The  allocation  map  usually  starts 
at  LSNl.  The  number  of  sectors  it  requires  varies  according  to 
how  many  bits  are  needed  for  the  map.  DD.MAP  specifies  the 
actual  number  of  bytes  used  in  the  map. 

Multiple  sector  allocation  maps  allow  the  number  of  sectors/clus- 
ter to  be  as  small  as  possible  for  high  volume  media. 

The  FORMAT  utility  bases  the  size  of  the  allocation  map  on  the 
size  and  number  of  sect(n's  per  cluster. 

The  DD.MAP  value  in  LSN  0  specifies  the  number  of  bytes  (in 

LSN  1)  that  are  used  in  the  map. 

Each  bit  on  the  disk  allocation  map  corresponds  to  one  sector 
clustOT  on  the  disk.  The  DD.BTT  value  in  LSN  0  specifies  the 
number  of  sectors  per  cluster.  The  number  is  an  integral  power 

of  2  (1,  2,  4,  8,  16,  and  so  on). 

If  a  cluster  is  available,  the  corresponding  bit  is  cleared.  If  it  is 
allocated,  non-existent,  or  physically  defective,  the  corresponding 
bit  is  set. 

ROOT  Directory 

This  file  is  the  parent  directory  of  all  other  files  and  directories 
on  the  disk.  It  is  the  directory  accessed  using  the  physical  device 
name  (such  as  /Dl).  Usually,  it  immediately  follows  the  Alloca- 
tion Map.  The  location  of  the  ROOT  directory  file  descriptor  is 
specified  in  DD.DIR.  The  ROOT  directory  contains  an  entry  for 
each  file  that  resides  in  the  directory,  including  oth&c 
directories. 

File  Descriptor  Sector 

The  first  sector  of  every  file  is  the  file  descriptor.  It  contains  the 
logical  and  physical  description  of  the  file. 
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The  following  table  describes  the  contents  of  the  file  descriptor. 


Name 

1?  fil  a  ^"1  \7£» 

Address 

(Bytes) 

Use 

FD.ATT 

$00 

1 

File  attributes:  D  S  PE  PW  PR 
jjj  w  It  (.see  n^t  cnartj 

rU.UWJN 

O 

z 

Owner's  user  ID 

1,11  \  T\  Am 

FD.DAT 

$03 

IT 

5 

Date  last  modified:  (Y  M  D  H 
M) 

FD.LNK 

$08 

1 

Li  nk  count 

FD.SIZ 

$09 

4 

File  size  (number  of  bytes) 

FD.  GREAT 

$0D 

3 

Date  created  (Y  M  D) 

FD.SEG 

$10 

240 

Segment  list  (see  next  chart) 

FD.ATT.  (The  attribute  byte)  contains  the  file  permission  bits. 
When  set  the  bits  indicate  the  following: 

Bit  7  Directory 
Bit  6  Single  user 
Bit  5  Public  esLecute 
Mt  4  Public  write 
Bit  3  Public  read 
Bit  2  Execute 
Bit  1  Write 
Bit  0  Read 

FD.SEG  (the  segment  list)  consists  of  a  maximum  of  48  5-byte 
entries  that  have  the  size  and  address  of  each  file  block  in  logical 

order.  Each  entry  has  the  block's  3-byte  LSN  and  2-byte  size  (in 
sectors).  The  entry  following  the  last  segment  is  zero. 

After  creation,  a  file  has  no  data  segments  allocated  to  it  until 
Ihe  fbrst  write.  (Write  operations  past  the  current  end-of-file 
cause  sectors  to  be  added  to  the  file.  The  first  write  is  always 
past  §m  ^od-c^-file.) 

If  the  file  has  no  segments,  it  is  given  an  initial  segment.  Usu- 
ally, this  segment  has  the  number  of  sectors  specified  by  the 
minimum  allocation  entry  in  the  device  descriptor.  If,  however, 
the  number  of  sectors  requested  is  more  than  the  minimum,  the 
initial  segment  has  the  requested  number. 
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Later  expansions  of  the  file  usually  are  also  made  in  minimum 
allocation  increments.  Whenever  possible,  OS-9  expands  the  last 
segment,  instead  of  adding  a  segment.  When  the  file  is  closed, 
OS-9  truncates  unused  sectors  in  the  last  segment. 

OS-9  tries  to  minimize  the  number  of  storage  segments  used  in 
a  file.  In  fact,  xmssy  files  have  ot%  om  §epa@tit.  In  such  cases, 
no  extra  Read  op^ations  are  needed  to  random^  access  any  byte 

in  the  file. 

If  a  file  is  repeatedly  closed,  opened,  and  expanded,  it  can 
become  fragmented  so  that  it  has  many  segments.  You  can  smMt 
this  fragmentation  by  writing  a  byte  at  the  highest  address  yon 
want  to  be  used  on  a  file.  Do  this  b^re  writing  any  oth@r  da^. 

Directories 

Disk  directories  are  files  that  have  the  D  attribute  set.  A  direc- 
tory contains  an  integral  number  of  entries,  each  of  which  can 
hold  the  name  and  LSN  of  a  file  or  another  directory. 

Each  directory  entry  contains  29  bytes  for  the  filename^  Mlowed 
by  the  three  bytes  for  the  LSN  of  the  file's  descriptor  sector.  The 
filename  is  left-justified  in  the  field,  with  the  most  significant  bit 
of  the  last  character  set.  Unused  entries  have  a  zero  byte  in  the 

first  filename  character  position. 

Every  disk  has  a  master  directory  called  the  ROOT  directory. 
The  DD-DIB  mMe  in  LSN  0  (identification  sector)  specifies  the 
starting  sector  of  the  ROOT  directory. 

The  RBF  Manager  Definitions  of  the  Path 
Descriptor 

As  stated  earlier  in  this  chapter,  the  PD.FST  section  of  the  path 

descriptor  is  reserved  for  and  defined  by  the  file  manager.  The 
following  table  describes  the  use  of  this  section  by  the  RBF  man- 
ager. Far  your  convraiience,  it  also  includes  the  other  sections  of 
the  PD. 
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Relative  Size 
Name  Address  (Bytes)  Use 


Universal  iittte  (Same  far  all  file  WB^^'M  ssa&  i@vlc@  drivers) 

liO        1  Patkramber 
PD.MOD      $01         1  Access  m©il 

2  =  write, 

3  =  update 

PD.CNT      $02         1  Number  of  open  images  (paths 

using  this  PD) 

PD.DEV      $03         2  Address  of  the  associated 

ilAe  table  entry 

PD.CPE      $05         1  Owawst  process  ID 

PD.RGS      $06        2  Mdreas  of  ^  eall»'g  iMi 

register  steck 

PD.BUF  $08  2  Address  of  the  256-byte  data 
 buffer  (if  used)  

Relative  Size 

IfraBB  M&emss  (Bytes)  Use  

TheRBF  mafeteprPath  Descriptor  Definitions  (PD.FST  Section) 

PDwSMF      $0A         1  State  fiag: 

Bit  0  =  current  buffer  is 
altered 

Bit  1  =  current  sector  is  in 
the  buffer 

Bit  2  =  ieicrfptoir  sector  is 
in  the  buffer 

PD.GP         $0B         4  Current  logical  file  position 

(byte  address) 

PD.SIZ        $0F         4  File  size 

PD.SBL       $13  3  Segment  beginning  logical  sees- 

tor  number  (LSN) 

PD.SBP       $16  3  Segment  beginning  physical 

sector  number  (PSN) 
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Name 

Uelative 
Address 

Size 
(Bytes) 

Use 

FD.SSZ 

$19 

3 

Segm@Eit  size 

PD.DSK 

$1C 

2 

Disk  ID  (for  internal  use  only) 

PD.DTB 

$1E 

Address  of  drive  table 

Name 

Relative  Size 
Address  (Bytes) 

The  BBf  mBmsese  OpUm  Sectim  Befinitions  (FD.OPT  Section) 

(Copied  from  the  device  descziptof) 

PD.DTP 

$20 

1 

Device  class: 

0  =  SCF 

1  =  RBF 

2  =  PIPE 

3  =  SBF 

PD.DRV 

$21 

1 

Drive  number  (0..re) 

PD.STP 

$22 

1 

Step  rate 

PD.TYP 

$23 

1 

Dev^lf^e 

PD.DNS 

$24 

1 

Densiliy  wpa^iUi^ 

PD.CYL 

$25 

2 

Numb^  dS  cyliniers  (^^s) 

PD.SID 

$27 

1 

Number  of  sides  (sur&ces) 

PD.VFY 

$28 

1 

0  =  verify  disk  writes 

PD.SCT 

$29 

2 

D^ttli  number  of  sectors  per 
track 

PD.TOS 

$2B 

2 

Default  number  of  sectors  per 

track  (Track  0) 

PD.ILV 

$2D 

1 

Sector  interleave  factor 

PD.SAS 

$2E 

1 

Segment  allocation  size 

PD.TFM 

$2F 

1 

DMA  transfer  mode 

PD.EXTEN 

$30 

2 

Path  extension  for  record 
locking 

PD,STOFF 

$32 

1 

Sector/track  c^sets 
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Relative  Size 
Name  Address  (Bytes)  Use 

(Not  copied  from  the  device  descriptor): 


PD.ATT 

$33 

1 

File  attributes 

(D  S  PE  PW  PR  E  W  R) 

PD.FD 

$34 

3 

Pile  descriptor  PSN 

PD.DFD 

$37 

3 

Directory  file  descriptor  PSN 

PD.DCP 

$3A 

4 

File's  directory  entry  pointer 

PS.DVT 

$3E 

2 

Address  of  the  device  table 

entry 


Any  values  not  determined  by  this  table  default  to  zero. 

RBF-Type  Deirioe  Desedptfn*  Modules 

Tliis  section  describes  the  use  d  the  initialization  table  con- 
tained in  the  device  descriptor  modules  for  RBF-type  devices. 
The  following  values  are  those  the  I/O  manager  copies  from  the 
device  descriptor  to  the  path  descriptor. 
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Name 

Relative 

Address 

Size 
(Bytes) 

Use 

$o-$ii 

Standard  device  descriptor 
module  he£tder 

IT.DTP 

$12 

1 

Device  type: 

0  =  SCF 

1  —  PRT? 

2  =  PIPE 

3  =  SBF 

IT.DRV 

$13 

1 

TItivp  T*ii]Tnl*)pr 

IT.STP 

$14 

1 

Step  rate 

IT.TYP 

$15 

1 

Device  type  (see  RBF  path 

1 

ivieuia  u0j.sixy. 
Always  1  (double) 
(see  following  information) 

IT.CYL 

$17 

2 

Number  of  cylinders  (tracks) 

IT.SID 

$19 

1 

Number  of  sides 

TT  \7TrV 

1 

0  =  \ferify  disk  writes 

1  =  no  verify 

Xl.lSOl 

ueiauiii  numDer  oi  secburs  per 
track 

IT.TOS 

$1D 

2 

Default  number  of  sectors  ■p&c 

IT.ILV 

$1F 

1 

Sector  interleave  &ctar 

rr.sAS 

$20 

1 

Mfnimam  size  of  segment  allo- 
cation (number  of  sectors  to  be 
allocated  at  one  time) 

IT.DRV  is  used  to  associate  a  1-byte  integer  with  each  drive 
that  a  controller  handles.  Numb^  tile  triM  ibr  msh.  eontroller 
as  0  to  n-1,  where  n  is  the  maximum  number  <£  drives  the  con- 
troller can  handle. 
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IT.TYP  specifies  the  device  type  (all  types). 

Bit  0  —  0  =  5-inch  floppy  diskette 

Bit  5  —  Q  =  Non-Color  Computer  format 
1  =  Color  Computer  format 

Hl  f  ^  O  =  Standard  OS-9  format 
1  =  Non-standard  format 

Bit  ?  —  0  =  Floppy  diskette 
1  =  Hard  disk 

IT.DNS  specifies  the  density  capabilities  (floppy  diskette  only). 

Bit  0  —  0  =  Single-bit  density  (FM) 

1  =  Double-Wt  density  (MFM) 

Bit  1  —  0  =  Single-track  density  (5-inch,  48  tracks  per 

1  =  Dantele-traek  ieasf^  CS-tehi  it  tracks  per 
inch) 

IT.SAS  specifies  the  minimum  number  of  sectors  allowed  at  one 
time. 

RBF  Record  Locking 

Record  locking  is  a  general  term  that  refers  to  methods  designed 
to  preserve  the  integrity  of  files  that  can  be  accessed  by  more 
than  one  user  or  process.  The  OS-9  implementation  of  record 
locking  is  designed  to  be  as  invisible  as  possible.  This  means 
that  existing  programs  do  not  have  to  be  rewritten  to  take 
advantage  of  record  locking  facilities.  You  can  usually  write  new 
programs  without  special  concern  for  multi-user  activity. 

Record  locking  involves  detecting  and  preventing  conflicts  during 
record  access.  Whenever  a  process  modifies  a  record,  the  system 
locks  out  other  procedures  from  accessing  the  file.  It  defers 
access  to  other  procedures  until  it  is  safe  for  them  to  write  to  the 
record,  Tim  ^ekma.  iaes  lai  losk  recffl^ds  Atiring  reastoi  w,  multi- 
ple proGesses  Can  read  the  record  at  the  same  time. 
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Record  Locking  and  Unlocking 

To  detect  conflicts,  OS-9  must  recognize  when  a  record  is  being 
updated.  The  RBF  manager  provides  true  record  locking  on  a 
byte  basis.  A  typical  record  update  sequence  is: 

QS9   I$Reacl  program  reads  record 

RECORD  IS  LOCKED 

program  updates  record 

059   I$Seek  reposition  to  record 

089  I$Mrite        record  is  rewritten 
RECORD  IS  RELEASED 

When  a  file  is  opened  in  update  mode,  any  read  caus^  locking 
of  the  record  being  accessed.  This  happens  because  the  RBF 
manager  cannot  determine  in  advance  if  the  record  is  to  be 
updated.  The  record  stays  locked  out  until  the  next  read,  write, 
or  close. 

However,  when  a  file  is  opened  in  the  read  or  execute  modes,  the 
syst^  does  not  Hoek  acces^  records  because  tibe  recrards  cannot 
be  updated  in  these  two  modes. 

A  subtle  but  important  problem  exists  for  programs  that  interro- 
gate a  data  base  and  occasionally  update  its  data.  If  you  neglect 
to  release  a  record  after  accessing  it,  the  record  might  be  locked 
up  indefinitely.  This  problem  is  characteristic  of  record  locking 
systems  and  you  can  avoid  it  with  careful  programming. 

Only  one  portion  of  a  file  can  be  locked  out  at  a  time.  If  an 
application  requires  more  than  one  record  to  be  locked  out,  open 
multiple  paths  to  the  same  file  and  lock  the  record  accessed  by 
each  patii.  RBF  notices  that  the  same  procass  owns  both  patfa^ 
and  keeps  them  firom  locking  each  other  out. 
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Non-Shareable  Files 

Sometimes  (although  rarely),  you  must  create  a  file  that  can 
never  be  accessed  by  more  than  one  user  at  a  time.  To  lock  the 
file,  you  set  the  single-user  (s)  bit  in  the  file's  attribute  byte.  You 
can  do  this  by  using  the  proper  option  when  the  file  is  created, 
or  later  using  the  OS-9  METR  command.  Once  the  single-user 
bit  is  set,  only  one  user  can  open  the  file  at  a  time.  If  other  users 
attempt  to  open  the  file,  Error  253  is  returned.  Note  however, 
that  non-shareable  means  only  one  path  can  be  opened  to  a  file 
at  one  time.  Do  not  allow  two  processes  to  concurrently  access  a 
iwdtaFfi&Mg  fil(g  l^rnm^  the  same  f a£h. 


More  commealy,  you  neei!  to  declare  a  file  as  shiglei-usef  miy 
during  the  execution  of  a  specific  program.  You  can  do  this  by 
opening  the  file  with  the  single-user  bit  set.  For  example,  sup- 
pose a  process  is  sorting  a  file.  With  the  file's  single-user  bit  set, 
OS-9  treats  the  file  exactly  as  though  it  had  a  single-user  attrib- 
Vitm,  IS  ams&m  preeess  alteapls  lo  agm  tlie  fils,  (M-9  mtmm 

You  can  duplicate  non-shareable  paths  by  using  the  I$Dup  sys- 
tem call.  This  means  that  it  can  be  inherited,  and  therefore 
accessible  to  more  than  one  process  at  a  time.  Single-user  mesms 
that  the  file  can  be  opened  only  once. 

End-of-FUe  Lock 

A  special  case  of  record  locking  occurs  when  a  user  reads  or 
writes  data  at  the  end  of  a  file,  creating  an  EOF  Lock.  An  EOF 
Lock  keeps  the  end  of  the  file  locked  out  until  a  process  performs 
a  READ  or  WRITE  that  is  not  at  the  end  ttf  the  file.  It  i^esrents 
problems  that  might  otherwise  occur  when  two  users  want  to 
simultaneously  extend  a  file.  The  EOF  Lock  is  the  only  case  in 
which  a  WRITE  call  automatically  causes  portions  of  a  file  to  be 
locked  out.  An  interesting  and  useful  side  effect  of  the  EOF  Lock 
fimction  occurs  if  a  larogFam  creates  a  file  for  sequential  output. 
As  soon  as  the  program  creates  the  file,  EOF  Lock  is  set  and  no 
other  process  can  pass  the  writer  in  processing  the  file.  For 
example,  if  an  assembler  redirects  a  listing  to  a  disk  file,  and  a 
spooler  utility  tries  to  print  a  line  from  the  file  before  it  is  writ- 
ten, record  locking  makes  the  spooler  \rait  and  stay  at  least  one 
step  behind  the  assembler. 
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Deadlock  Detection 

A  dmdty  embrme,  &t  deadlock,  tf^ieally  €»ecurs  when  two  pro- 
cesses attempt  to  gain  control  of  two  or  more  disk  areas  at  the 
same  time.  If  each  process  gets  one  area  (locking  out  the  other 
process),  both  processes  become  permanently  stuck.  Each  waits 
for  a  segment  that  can  never  become  free.  This  situation  is  not 
restricted  to  amy  particular  record  locking  scheiHe  m  of^^timg 
system. 

When  a  deadly  embrace  occurs,  RBF  returns  a  deadlock  error 
(Error  254)  to  the  process  that  caused  OS-9  to  detect  the  dead- 
lock. To  avoid  deadlocks,  make  sure  that  processes  always  access 
records  of  shared  files  in  the  same  sequence. 

When  a  deadlock  error  occurs,  it  is  not  sufficient  for  a  program 
to  retry  the  operatiott  that  caused  the  error.  If  all  proeesse§  use 

this  strategy,  none  can  ever  succeed.  For  any  process  to  proceed, 
at  least  one  must  cancel  operation  to  release  its  control  over  a 
requesting  segment. 

RBF-Type  Device  Driver  Modules 

An  RBF-type  device  driver  module  contains  a  package  of  subrou- 
tines that  perform  sector-oriented  I/O  to  or  from  a  specific  hard- 
ware controller.  Such  a  module  is  usually  re-entrant.  Because  of 
this,  one  copy  of  one  device  driver  module  can  simultaneously 
run  several  devices  that  use  identical  I/O  controllers. 

The  I/O  manager  allocates  a  permanent  memory  area  for  each 
device  driver.  The  size  of  the  memory  area  is  given  in  the  device 
driver  module  header.  The  I/O  manager  and  the  RBF  manager 
use  some  of  this  area.  The  device  driver  can  use  the  rest  in  any 
manner.  This  area  is  used  as  follows: 

Th&  'BMW  Device  Memory  Area  Definitions 
Relative  Size 

Name         hMxmss  (Bytes)  Use  


V.PAGE  $00  1 
V.PORT       $01  2 


Port  extended  address  bits 
A20-A16 

Device  base  address  (defined 
by  the  I/O  managw) 
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Name 


Relative 
Address 


Size 
(Bytes) 


Use 


V.LPRC 

V.BUSY 

V.WAKE 

V.USER 
V.NDRV 


DRVBEG 
TABLES 

FREE 


$03 
$04 
$05 


$06 


$0P 
$0F 


i 
0 


ID  of  the  last  active  process 
(not  used  by  RBP  device 

drivers) 

ID  of  the  current  process  using 
driver  (defined  1?r  RBF) 
0  =  no  current  process 

ID  of  the  process  waiting  for 
I/O  completion  (defined  by  the 
device  dxbrer) 

Beginning  of  file  manager  spe- 
cific storage 

Maximum  number  of  drives 
the  controller  can  use  (defined 
by  the  device  driver) 

Reserved 

Beginning  of  the  drive  tables 


13fEVMEN*N  Space  for  number  of  tables 

reserved  in) 

0  Beginning  of  space  available 

for  driver 


These  values  are  defined  in  files  in  the  DEPS  directory  W  tito 
Development  Package  disk. 

TABLES.  This  area  contains  one  table  for  each  drive  that  the 
controller  handles.  (The  RBF  manager  assumes  that  there  are  as 
many  tables  as  indicated  by  V.NDRV.)  Some  time  after  the 
driver  Init  routine  is  called,  the  RBF  manager  issues  a  request 
to  the  driver  to  read  Lffil  0  from  a  drive  table  by  copying  ih© 
first  part  of  LSN  0  (up  to  DD.SIZ)  into  the  table.  Ebllowing  is 
the  format  of  each  drive  table: 
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Relative  Size 
Name         Address  (Bytes)  Use 


DD.TOT 

$00 

3 

Number  of  sectors. 

DD.TKS 

$03 

1 

Track  size  (in  sectors). 

DD.MAP 

$04 

2 

Number  of  bytes  in  the  alloca- 
tion bit  map. 

$06 

2 

Numbef  of  sectors  per  bit 
(cluster  size). 

DD,DIR 

$08 

3 

Address  (LSN)  of  the  ROOT 
directory. 

DD.OWN 

$0B 

2 

Owner's  user  number. 

DD.ATT 

$0D 

1 

Disk  access  attributes 
(D  S  PE  PW  PR  E  W  R). 

DD.DSK 

$0E 

2 

Disk  ID  (a  pseudo-random 
TmTnVtpr  iispH  f.n  dptprt  Hi^lcpttp 
swaps). 

$10 

1 

Media  fi^rmat. 

DD.SPT 

$11 

2 

Number  of  sectors  per  track. 

(Track  0  can  use  a  different 
value  specified  by  IT.TOS  in 

LUC!  wSVXKfS?  UGSUXX^bUX 

DD.RES 

$13 

2 

Reserved  fiir  future  use, 

DD.SIZ 

$15 

0 

Minimum    size    of  device 

descriptor. 

V.TRAK 

$15 

2 

Number  of  the  current  track 
(the  track  that  the  head  is  on, 
and  the  track  updated  by  the 

driver). 

V.BMB 

$17 

1 

Bit-map  use  flag: 

0  =  Bit  map  is  not  in  use. 
(Disk  driver  routines 
must  not  alter  V.BMB.) 

V.FILEHD 

$18 

2 

Open  file  list  for  this  drive. 
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Relative  Size 
Name  Address  (Bytes)  Use 


?,issEm  $iA 

2 

Disk  ID. 

V.BMAPSE  $1G 

1 

of  bitmap. 

V.MAPSCT  $1D 

1 

Lowest  reasonable  bitmap 
sector. 

V.RESBIT  $1E 

1 

Reserved  bitmap  sector. 

vmimw  iiF 

1 

SectoR/tirii^  l^yte. 

V.SCOPST  $20 

1 

Sector    offset    split  from 
V.SCTKOF. 

V.TKOFST  $21 

1 

Track    offset    split  from 
V.SCTKDF. 

RESERVED  $22 

4 

Reserved  far  future  use. 

DRVMEN  $26 

Size  of  each  drive  table. 

Hie  format  attributes  (DD.FMT)  are  these: 

m  BO  =  Number  of  sides 

0  =  Single-sided 

1  =  Double-sided 


Bit  Bl  =  Density 

0  =  Single-density 

1  =  Double-density 

Bit  B2  =  Track  density 

0  —  Single  (48  tracks  per  inch) 

1  =  Double  (96  tracks  per  inch) 

RBF  Device  Driver  Subroutines 

Like  all  device  driver  modules,  RBF  device  drivers  use  a  stan- 
dard executable  m&amy  modu:le  fimnat. 

The  execution  offset  address  in  the  module  header  points  to  a 
branch  table  that  has  six  3-byte  entries.  Each  entry  is  typically 
a  long  branch  (LBRA)  to  the  corresponding  suhroutiieie.  'ths 
branch  table  is  defined  as  follows: 
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ENTRY 


LBRA 
LBRA 
LBRA 
LBRA 
LBRA 
LBRA 


INIT 


Initialize  drive 


READ 

WRITE 

GETSTA 

SETSTA 

TERM 


Read  sector 
Write  sector 
Get  status 
Set  status 


Terminate  device 


Ensure  that  each  subroutine  exists  with  the  C  bit  of  the  condi- 
tion code  register  cleared  if  no  error  occurred.  If  an  error  occuirs, 
set  the  C  bit  and  return  an  appropriate  error  code  Register  B. 

The  rest  of  this  chapter  describes  the  RBF  device  driver  subrou- 
tines and  their  entry  and  exit  conditions. 
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Init  Initializes  a  device  and  the  device's  memory 
area. 

Entry  Conditions: 

Y     =  adiress  of  the  device  descriptor 
U     =  address  of  the  device  memory  area 

Esdl  ConeKtionsi 

CC  =  carry  set  on  error 
B     =  error  code  (if  any) 

Additional  InformaMon* 

•  If  you  want  OS-9  to  verify  disk  writes,  use  the  Request 

Memory  system  call  (F$SRqMem)  to  allocate  a  256-byte 
buffer  area  in  which  a  sector  can  be  read  back  and  verified 
after  a  write. 

•  You  must  initialize  the  device  memory  area.  For  floppy 
diskette  controllers,  initialization  typically  consists  of: 

1.  Initializing  V.NDRV  to  the  number  of  drives  with  which 
the  controller  works 

2.  Mti^Jizing  DD.TOT  (in  the  drive  table)  to  a  non-zero 
value  so  that  Sector  0  can  be  read  or  written 

3.  Initialiang  V.TRAK  to  $FF  so  that  the  first  seek  finds 
Track  0 

4.  Placing  the  IRQ  service  routine  on  the  IRQ  polling  list, 
using  the  Set  IRQ  system  call  (F$IRQ) 

5.  Initializing  the  device  control  registers  (enabling  inter- 
rupts if  necessary) 

•  Prior  to  being  called,  the  device  memory  area  it  ^^&3i.  (set 
to  zero),  except  for  V.PAGE  and  V.PORT.  (These  areas  con- 
tain the  24-  bit  device  address.)  Ensure  the  driver  initial- 
izes each  drive  table  appropriately  for  the  type  of  diskette 
that  the  driver  expects  to  be  used  on  the  corresponding 
drive. 


5-18 


Random  Bhck  File  MBmager  1 5 


Read  Reads  a  256-byte  sector  from  a  disk  and 
places  it  in  a  256-l^te  sector  buffer. 

Entry  Conditions: 

B  =  MSB  of  the  disk's  LSN 

X  =  LSB  of  the  disk's  LSN 

Y  =  address  of  the  path  descriptor 

U  =  address  of  the  device  memory  area 

Exit  Conditions: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  The  followii^  is  a  typical  routine  for  using  Read: 

1.  Get  the  sector  buffe*  address  from  PD-BUF  in  the  path 

descriptor. 

2.  Get  the  drive  number  from  PD.DRV  in  the  path 

descriptor. 

3.  Compute  the  physical  disk  address  from  the  logical  sec- 
tor number. 

4.  Initiate  the  Read  operation. 

5.  Copy  V.BUSY  to  V.WAKE.  The  driver  goes  to  sleep  and 
waits  for  the  I/O  to  complete.  (The  IRQ  service  routine  is 
responsible  for  sending  a  wakeup  signal.)  After  awaken- 
ing, the  driver  tests  V.WAKE  to  see  if  it  is  clear.  If  it 
isn't  clear,  the  driver  goes  back  to  sleep. 

•  Whenever  you  read  LSN  0,  you  must  copy  the  first  part  of 
this  sector  into  the  proper  drive  table.  (Get  the  drive  num- 
ber from  PD.DRV  in  the  path  descriptor.)  The  number  of 
bytes  to  copy  is  in  DD.SIZ.  Use  the  drive  number  (PD.DRV) 
to  compute  the  offset  for  the  corresponding  drive  table  as 
follows: 
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LDA  PD.DRV.Y 
LDB  #DRVMEN 

MUL 

LEAX  DRVBEG.U 
LEAX  D.X 


©et  the  dr Ive  number 
Get  the  size  of  a 

drive  table 

Get   the  address  of 
the  first  table 
Compute  the  address 
of    the  table 
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Write  Writes  a  256-byte  sector  buffer  to  a  disk. 

Entry  Conditions: 

B  =  MSB  of  the  disk  LSN 

X  =  LSB  of  the  disk  LSN 

Y  =?  address  of  the  path  descriptor 

U  =  address  of  the  device  memory  area 

Exit  Conditions: 

CC    =  carry  set  on  raror 
B      =  error  code 

Additional  Infomiation: 

•  Bbllowing  is  a  typical  routine  for  using  Write: 

1.  Get  the  sector  buffer  address  from  PD.BUF  in  the  path 

descriptor. 

2.  Get  the  drive  number  from  PD.DRV  in  the  path  descriptor. 

3.  Compute  the  physical  disk  address  from  the  bgical  sector 
mmh&c. 

4.  Ihitiate  the  'Wcite  operation. 

5.  Copy  V.BUSY  to  V.WAKE.  The  driw  then  goes  to  sleep 
and  waits  for  the  I/O  to  complete.  (The  IRQ  service  routine 
sends  the  wakeup  signal.)  After  awakening,  the  driver  tests 
V.WAKE  to  see  if  it  is  clear.  If  it  is  not,  the  driver  goes 
back  to  sleep.  If  the  disk  controller  cannot  be  interrupt-dri- 
ven,  it  is  necrasary  to  perform  a  programmed  1/0  transfer. 

6.  If  PF.VFY  in  the  path  descriptor  is  equal  to  zero,  read  the 

sector  back  in  and  verify  that  it  is  written  correctly.  Verifi- 
cation usually  does  not  involve  a  comparison  of  all  of  the 
data  bytes. 

•  If  disk  writes  are  to  be  verified,  the  Init  routine  must 
request  the  buffer  in  which  to  place  the  sector  when  it  is 
read  back.  Do  not  copy  LSN  0  into  the  drive  table  when 
reading  it  back  for  verification. 
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•  Use  the  drive  number  (PD.DRV)  to  compute  the  offset  to 
the  corresponding  drive  table  as  shown  for  the  Read 
routine. 
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Getstats  and  Setstats 

Reads  or  changes  device's  operating  parameters. 

'Entif  Ofsmditions: 

U     =  cuMress  of  the  dmke  memory  area 
Y      =  address  of  the  path  descriptor 
A      =  status  code 

Exit  Conditions; 

B  =  error  code  (if  any) 
CC    =  carry  set  on  error 

Additional  Information: 

•  Get/set  the  device's  operating  parameters  (status)  as  speci- 
fied for  the  Get  Status  and  Set  Status  system  calls.  Getsta 
and  Setsta  are  wild  card  calls. 

•  It  might  be  necessary  to  examine  or  change  the  register 
stack  that  contains  the  values  of  the  6809  register  at  the 
time  of  ths  call.  The  address  of  the  regist^  stack  is  in 

PD.RGS,  which  is  located  in  the  path  descriptor.  You  can 
use  the  following  offsets  to  access  any  value  in  the  register 
stack: 


Reg. 

Relative 
Addr. 

Size 

6809  Reg. 

R$CC 

$00 

1 

Condition  Code  Reg. 

R$D 

$01 

2 

Register  D 

R$A 

$01 

1 

Register  A 

R$B 

$02 

1 

Register  B 

R$DP 

$03 

1 

Register  DP 

R$X 

$04 

2 

Register  X 

R$Y 

$06 

2 

Register  Y 

R$U 

$08 

2 

Register  U 

R$PC 

$0A 

2 

Program  Counter 

•  Register  D  overlays  Registers  A  and  B. 
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Term  Terminate  a  device. 


Entry  Conditions: 

U     =  address  (f  the  device  memory  arm 

dC  =  mjcty  set  on  error 
B     =  error  code  (if  any) 

AdidULtional  InlofiHtation: 

•  This  routine  is  called  'when  bl  dmim  i*  no  linger  in  ise  in 


the  system  (when  the  link  count  of  its  device  d^criptor 

module  becomes  zero). 

•  Following  is  a  typical  routine  for  using  Term: 

1.  Wait  until  any  pending  I/O  is  completed. 

2.  Disable  the  device  interrupts. 

3.  Remove  the  device  from  the  IRQ  polling  list. 

4.  If  the  Init  routine  reserved  a  256-byte  buffer  for  verify- 
ing disk  writes,  return  the  memory  with  the  Return 
%8mem  system  call  (F$SRtMem). 
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IRQ  Service  Routine 

Services  device  interrupts. 

•  The  HQ  S^^ce  routine  sends  a  wakeup  signal  to  the  jjrd- 

cess  indicated  by  the  process  ID  in  V.WAKE  when  the  I/O 
is  complete.  It  then  clears  V.WAKE  as  a  flag  to  indicate  to 
the  main  progreun  that  the  IRQ  has  indeed  occurred. 

•  When  the  IRQ  service  routine  finishes  servicing  an  inter- 
rupt it  must  clear  the  carry  and  exit  with  an  RTS 
instruotei. 

•  Although  this  routine  is  not  included  in  the  device  6a\v&e 

module  branch  table  and  is  not  called  directly  by  the  RBF 
manager,  it  is  a  key  routine  in  interrupt-driven  drivers.  Its 
function  is  to: 

1.  Service  the  device  interrupts  (receive  data  from  device  or 
send  data  to  it).  The  IRQ  service  routine  puts  its  data 
into  and  get  its  data  from  buffers  that  are  defined  in  the 
device  memory  area. 

2.  Wake  up  a  process  that  is  waiting  for  I/O  to  be  com- 
pleted. To  do  this,  the  routine  checks  to  see  if  there  is  a 
process  ID  in  V.WAKE  (if  the  bit  is  non-zero);  if  so,  it 
sends  a  wakeup  signal  to  that  process. 

3.  If  the  device  is  ready  to  send  more  data,  and  the  output 
buffer  is  empty,  disable  the  device's  ready  to  transmit 
interrupts. 
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Boot  (Bootstrap  Module) 

Loads  the  boot  file  into  RAM. 

Entry  Condilions: 

None 

Exit  Conditions: 

D      =  size  of  the  boot  file  (in  bytes) 

X     =  euMress  at  which  the  bod  file  was  loaded  into  memory 
CC    =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  The  Boot  module  is  not  part  of  the  disk  driver.  It  is  a  sepa- 
rate module  that  is  stored  on  the  boot  track  of  the  system 
disk  with  0S9P1  and  REL. 

•  The  bootstrap  module  contains  one  subroutine  that  loads 
the  bootstrap  file  and  related  information  into  memory.  It 
uses  the  standard  executable  module  finrmst  with  a  module 

type  of  $C.  The  execution  offset  in  the  module  header  con- 
tains the  offset  to  the  entry  point  of  this  subroutine. 

•  The  module  gets  the  starting  sector  number  and  size  of  the 
OS9Boot  file  from  LSN  0.  OS-9  allocates  a  memory  area 
large  enough  for  the  Boot  file.  Then,  it  loads  the  Boot  file 
into  this  mmms  area. 

•  fbllowing  is  a  tjfpnl  soutine  ir  using  Boot: 

1.  Bead  LSN  0  fhan  the  disk  into  a  buffer  area.  The  Boot 

module  must  pick  its  own  buffer  area.  LSN  0  contains 
the  values  for  DD.BT  (the  24-bit  LSN  of  the  bootstrap 
file),  and  DD.BSZ  (the  size  of  the  bootstrap  file  in  l^ytes). 

2.  Get  the  24-bit  LSN  of  the  bootstrap  file  firom  DD.BT. 

3.  Get  the  size  of  the  bootstrap  file  from  DD.BSZ.  The  Boot 
module  is  contained  in  one  logically  contiguous  block 
beginning  at  the  logical  sector  sp^fied  in  DD.BT  and 
extending  for  DD,BSZ/256-l-l  sectors. 
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4.  Use  the  OS-9  Request  Sysmem  system  call  (F$SRqMem) 
to  request  the  memory  area  in  which  the  Boot  file  is 
loaded. 

5.  Read  the  Boot  file  into  this  memory  area. 

6.  Return  the  size  of  the  Boot  file  and  its  location.  Boot  file 
is  loaded. 
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Chapter  6 


Sequential  Character 
File  Manager 


The  Sequential  Character  File  Manager  (SCF)  supports  devices 
that  operate  on  a  character-by-character  basis.  These  include 
terminals,  printers,  and  modems. 

SCF  is  a  re-entrant  subroutine  package.  The  I/O  manager  calls 
the  SCF  manager  for  I/O  system  handling  of  sequential,  charac- 
ter-oriented devices.  The  SCF  manager  includes  the  extensive  I/O 
editing  functions  tj^ical  of  line-oriented  operation,  such  as: 

•  backspace 

•  line  delete 

•  line  repeat 

•  auto  line  feed 

•  screen  pause 

•  return  delay  padding 

The  SCF-type  device  driver  modules  are  CC3I0,  PRINTER,  and 
RS-232.  They  run  the  video  display,  printer,  and  serial  ports 
respectively.  See  the  OS-9  Commands  manual  for  additional 
Color  Computer  I/O  devices. 

SCF  Line  Editing  Functions 

Hie  SCF  manager  supports  two  sets  of  read  and  write  functions. 
I$Read  and  I$Write  pass  data  with  no  modification.  I$ReadLn 
and  I$WritLn  provide  full  line  editing  of  device  functions. 

Read  and  Write 

The  Read  and  Write  system  calls  to  SCF-type  devices  correspond 
to  the  BASIC09  GET  and  PUT  statements.  While  they  perform 
little  modification  to  the  data  they  pass,  they  do  filter  out  key- 
board interrupt,  keyboard  terminate,  and  pause  character.  (Edit- 
ing is  disabled  if  the  corresponding  character  in  the  path 
descriptor  contains  a  zero.) 
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Carriage  returns  are  not  followed  by  line  feeds  or  nulls  automat- 
ically, and  the  high  order  bits  are  passed  as  sent/received. 

T^bA  lim  ioiid  line 

The  Read  lillie  and  Write  Line  system  calls  to  SCF-type  devices 
correspond  to  the  BASIC09  INPUT,  PRINT,  READ,  and  WRITE 
statements.  They  provide  full  line  editing  of  all  functions  enabled 
&r  a  particula]*  device. 

The  system  initializes  I$ReadLn  and  I$WritLn  functions  when 
you  first  use  a  particular  device.  (OS-9  copies  the  option  table 
from  the  device  descriptor  table  associated  with  liie  specific 
device.) 

Later,  you  can  alter  the  calls — either  from  assembly-language 
programs  (using  the  Get  Status  system  call),  or  from  the  key- 
board (using  the  TMODE  command).  All  bytes  transferred  by 
Readln  and  Writln  have  the  high  order  bit  cleared. 

SCF  Definitions  of  the  Path  Descriptor 

The  PD.FST  and  PD.OPT  sections  of  the  path  descriptor  are 
reserved  for  and  used  by  the  SCF  file  manager. 

The  following  table  describes  the  SCF  manager's  use  of  PD.FST 
and  PD.OPT.  Ibr  your  convenience,  the  table  also  includes  the 
other  sections  of  the  PD  . 

The  PD.OPT  section  contains  the  -^lues  that  determine  the  line 
editing  functions.  It  contains  many  device  operating  parameters 
that  can  be  read  or  written  by  the  Set  Status  or  Get  Status  sys- 
tena  call.  Any  values  Dot  set  by  this  table  default  to  zero. 

Note:  You  can  disable  most  of  the  editing  functions  by  set- 
ting the  corresponding  control  character  in  the  path 
descriptor  to  zero.  Yon  can  use  the  Siet  Status  syitan  call 
or  the  TMODE  command  to  do  this.  Or,  you  can  go  a  step 
further  by  setting  the  corresponding  control  character  value 
in  the  device  descriptor  module  to  zero. 

To  determine  the  default  settings  for  a  specific  device,  you  can 
inspect  the  device  descriptor. 
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B^tive  Size 
Nmam         JkiMxma  (Bytes) 


Universal  Section  (Same  &r  all  file  managers) 
PD.PD  $00  1      Path  number 

PD.MOD  $01  1      Access  mode: 

1  =  read 

2  = 

3  =  update 

PD.CNT  $02  1      Number  of  open  images  (paths 

using  this  PD) 

PD.DEV  $03  2      Address  of  the  associated 

device  table  &atry 

PD.GPR  $05  1      Current  process  ID 

PD.RGS  $06  2      Address  of  the  caller's  6809 

register  stack 

PD.BUF  $08  2      Address  of  the  256-byte  data 

buffer  (if  used) 

Relative  Size 
Name  Address    (Bytes)  Use  

SCF  Path  Descriptor  Definitions  (PD.FST  Section) 

PD.DV2  $0A  2      Device  table  address  of  the  sec- 

ond (echo)  device 

PD.RAW  $0C  1      Edit  flag: 

0  i=  vmr  mode 

1  =  ^t  mode 

PD.MAX         $0D  2      Read  Line  maximum  character 

count 

PD.MIN  $0F  1       Devices  are  mine  if  cleared 

PD.STS  $10  2      Status  routine  module  address 

PD.STM  $12  2      Reserved  for  status  routme 
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Relative     Size  Use 
Name  Address  (Bytes) 


SCF  Option  Section  Definition  (PD.OPT  Section) 
(Copied  from  the  device  descriptor) 

PD.DTP  $20  1      Device  class: 

0  =  SCF 

1  =  RBF 

2  =  PIPE 

3  =  SBF 

PD.UPC  $21  1  Case: 

0  =  upper  and  lower 

1  =  upper  only 

PD.BSO  $22  1  Backspace: 

0  =  baekspaee 

1  =  backspace,  space  and 

backspace 

PD.DLO  $23  1  Delete: 

0  =  backspace  over  line 

1  =  carriage  return,  line 

feed 

PD.EKO  124  1  Echo: 

0  =  ao  mbo 

PD.ALP  $25  1      Auto  line  feed: 

0  =  no  auto  line  feed 

PD.NUL  $26  1       End-of-line  null  count: 

n  =  number  of  nulls 
sent  after  each  carriage 
return  or  carriage  return 
mi  line  feed  (n  =  $00-$FF) 

PD.PAU  $27  1      End  of  page  pause: 

0  =  no  pause 

PD.PAG  $28  1       Number  of  lines  per  pa^ 

PD.BSP  $29  1       Backspace  character 

PD.DEL  $2A  1       Delete-line  character 
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Name 

Relative 
Address 

Size 
(Bytes) 

Use 

SCF  Option  Section  Definition  00 

aatinaed  GPD,OPT  Seetite) 

irD.Mi\JM 

1 

End-of-recGrd  character  (End- 
of-line  character)  Read  only. 
iNoriiittiiy  set  to  tpuu. 
0  =  Terminate  read-line 

only  at  the  end  of  the 

file 

PD.EOF 

$2C 

1 

End-of-fil©  eharacter  (read 
only) 

PD.RPR 

$2D 

1 

Reprint-line  character 

PD.DUP 

$2E 

1 

Duplicate-last-line  charact^ 

PD.PSC 

$2F 

1 

Pause  character 

PD.INT 

$30 

1 

Kevhoard-intemiDt  character 

PD.QUT 

$31 

1 

K^board-temunate  character 

$32 

1 

Backspace-echo  character 

PD.OVF 

$33 

1 

Line-overflow  character  (bell 

1  CTRL  11  G  1) 

PD.PAR 

$34 

1 

Device-initialization  value 
(naritv) 

PD.BAU 

$35 

1 

PD.D2P 

$36 

2 

Of^pf  i'jt^  RM*nni\  f^Avir^A  nniTiA 
v/uoci'   lAJ   oc^uiiu  ucvxi>o   lira  1 1  ip 

string 

PP.XON 

$38 

1 

ACIA  XON  char 

PD.XOFF 

$39 

1 

ACIA  XOFF  char 

PD.ERR 

$3A 

1 

Most  recent  I/O  error  status 

PD.TBL 

$3B 

2 

Copy  of  device  table  address 

PD.PLP 

$3D 

2 

Path  descriptor  list  pointer 

PD.PST 

$3F 

1 

Current  path  status 

6-5 


OS-9  Technical  Reference 


PD.EOF  specifies  the  end-of-file  character.  If  this  is  the  first 
and  only  character  that  is  input  to  the  SCF  device,  SCF  returns 
an  end-of-'file  error  on  Read  or  Readln. 

PD.PSC  specifies  the  pause  character,  which  suspends  output  to 
the  device  before  the  next  end-of-record  character.  The  pause 
characta:  also  deletes  ax^  ^esSLbead  iztimt  &r  Readln. 

PDilNT  ^eclfl^  #ie  k^oard-intmtipt  cMracter.  When  the 

character  is  received,  the  system  sends  a  keyboard  terminate 
signal  to  the  last  user  of  a  path.  The  character  also  terminates 
the  current  I/O  request  (if  any)  with  an  error  identical  to  the 
keyboard  interrupt  signal  code. 

PD.QUT  specifies  the  keyboard-terminate  character.  When  this 
character  is  received,  tlie  systewi  sends  a  k^board  terminate 

signal  to  the  last  user  of  a  path.  The  system  also  cancels  the 
current  I/O  request  (if  any)  by  sending  error  code  identical  to  the 
k^board  interrupt  signal  code. 

PD.KAR  specifies  the  parity  information  for  external  serial 

devices. 

PD.BAIJ  specifies  baud  rate,  word  length  and  stop  bit  informa- 
tion in*  soSal  devices. 

FD.XOIf  contains  eitlsm  the  ctea^t^  tised  to  liable  transmis- 
sion of  characters  or  a  null  diaractar  that  disables  the  use  of 

XON. 

PD.XOFF  contains  either  the  character  used  to  disable  trans- 
mission of  characters  or  a  null  character  t^t  disables  the  use  of 
XOFF. 

SCF-Type  Device  Descriptor  Modules 

The  following  chart  shows  how  the  initialization  table  in  the 
device  descriptors  is  used  for  SCF-type  devices.  The  values  are 
those  the  I/O  manager  copies  from  the  device  descriptor  to  the 
path  descriptor. 

An  SCF  editing  fiindtiini  is  turned  off  if  its  corresponding  value 
is  set  to  zero.  Fbr  example,  if  IT.EOF  is  set  to  zero,  there  is  no 
end-of-file  character. 


6>6 


SeqtmMal  Charmtm'  Fiie  Manag&'  1 6 


Relative  Size 
Name  Address   (Bytes)  Use 


(header)  $00- 


11 

TT  TVtTP 

1 

IT.UPC 

$13 

1 

IT.BSO 

$14 

1 

IT.DLO 

$15 

1 

IT.EKO 

$16 

1 

IT,ALF 

$17 

1 

BP.HIIL 

$18 

1 

rr.PAU 

$19 

1 

IT.PAG 

$1A 

1 

IT.BSP 

$1B 

1 

IT.DEL 

$1C 

1 

IT.EOR 

$1D 

1 

IT.EOF 

$1E 

1 

IT.RPR 

$1F 

1 

Standard  device  descriptor 
module  header 

Device  class: 

0  =  SCF 

1  =  RBF 

2  =  PIPE 

3  =  SBF 

Case: 

0  =  upper-  and  lowercase 

1  =  uppercase  only 

Backspace: 

0  =  backspace 

1  =  backspace,  then  space 

and  backspace 

Delete: 

0  =  backspace  over  line 

1  =  carriage  return 

Echo: 
0  =  echo  off 

Autoline^i^^ 
0  =^  ituto  l£n@  feed  disabled 

End-of-Iine  null  count 

Pause: 

0  =  end-of-page  pause 
disabled 

Number  of  lines  per  page 

Backspace  character 

Delete-line  charact^ 

End-of-record  character 

End-of-file  character 

Reprint-line  character 
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Relative 

Size 
(Bytes)  Use 

IT.DUP 

$20 

1 

Duplicate-last-line  character 

IT.PSC 

$21 

1 

Pause  character 

IT.INT 

$22 

1 

Interrupt  character 

IT.QUT 

$23 

1 

Quit  character 

IT.BSE 

$24 

1 

Backspace  echo  character 

IT.OVF 

$25 

1 

Line-overflow  character  (bell) 

IT.PAR 

$26 

1 

Initialization  value — used  to 
initialize  a  device  control  reg- 
ister  when  a  path  is  opened  to 
it  (parity) 

IT.BAU 

$27 

1 

Baud  rate 

IT.D2P 

$28 

2 

Attached  device  name  string 
ofiGset 

IT.XON 

$2A 

1 

X-ON  character 

IT.XOFF 

$2B 

1 

X-OFF  character 

IT.COL 

$2C 

1 

Number  of  columns  for  display 

IT.ROW 

$2D 

1 

Number  of  rows  for  display 

IT.WND 

$2E 

1 

Window  number 

IT.VAL 

$2F 

1 

Data  in  rest  of  descriptor  is 
valid 

IT.STY 

$30 

1 

Window  type 

IT.CPX 

$31 

1 

X  cursor  position 

IT.CPY 

$32 

1 

Y  cursor  position 

mwQo 

$33 

1 

SiWeground  color 

IT.BGC 

$34 

1 

Backgroinid  cdm 

$35 

1 

Bord^  color 
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SCF-Type  Device  Driver  Modules 

An  SCF-type  device  driver  module  contains  a  package  of  subrou- 
tines that  perform  raw  (unformatted)  data  I/O  transfers  to  or 
from  a  specific  hardware  controllear.  Such  a  module  is  usually  re- 
entrant so  that  one  copy  of  the  module  can  simultaneously  run 
several  devices  that  use  identical  I/O  controllers.  The 
I/O  manager  allocates  a  pennanent  memory  area  for  each  con- 
troller sharing  the  driver. 

The  size  of  the  memory  area  is  defined  in  the  device  driver  mod- 
ule header.  'The  I/O  manager  and  SCF  use  some  of  the  mranory 

area.  The  device  driver  can  use  the  rest  in  any  way  (typically  as 
variables  and  buffers).  Typically,  the  driver  uses  the  area  as 
follows: 


Name 

Relative 
Address 

Size 
(Bytes) 

Use 

V.PAGE 

$00 

1 

Port  tended  24  bit  address 

V.PORT 

$01 

2 

Device  base  address  (defined 

\~W7  ^"r\o  T /(  1  m  o  n  Q  rroT*  1 
Uy  LUc  LI\J  IlldllctgtJI  7 

V.LPRC 

$03 

1 

ID  of  the  last  active  process 

V.BUSY 

$04 

1 

ID  of  the  active  process 
(defined  by  RBF): 
0  =  no  active  process 

V.WAKE 

$05 

1 

ID  of  the  process  to  reawaken 
after  the  device  completes  I/O 

(defined  by  the  device  driver): 
0  =  no  waiting  process 

V.USER 

$06 

0 

Beginning  of  file  manager 
specific  storage 

V.TYPE 

$06 

1 

Device  type  or  parity 

V.LINE 

$07 

1 

lines  left  trntil  the  end  of  the 

page 

V.PAUS 

$08 

1 

Pause  request: 
0  =  no  pause  requested 

V.nEVi 

$09 

2 

Attached  imim  mmmef  mm 

V.INTR 

$0B 

1 

Mimnxpt  eharaeter 
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Name 

Relative 

Address 

Size 

(Bytes)  Use 

V.QUIT 

$0C 

1 

Quit  character 

V.PCHR 

$0D 

1 

Pause  character 

V.ERR 

$0E 

1 

Error  accumulator 

V.XON 

$0F 

1 

XON  character 

V.XOFF 

$10 

1 

XOFF  character 

V.KANJI 

$11 

1 

Reserved 

V.KBUF 

$12 

2 

Reserved 

V.MODADR 

$14 

9 

xveserveu 

V.PDLHD 

$16 

2 

Path  descriptor  list  header 

V.RSV 

$18 

5 

Reserved 

v.bLr 

$1D 

0 

End  of  SCF  memory 
requirements 

FREE 

$1D 

0 

Free  for  the  device  driver  to 
use 

V.LPRC  contains  the  process  ID  of  the  last  process  to  use  the 
device.  The  IRQ  service  routine  sends  this  process  the  proper  sig- 
nal if  it  jmsiTKB  a  quit  dhfiracter  or  an  intarrupt  character. 
V.LPRC  is  «aei  1^  SCF. 

V.BUSY  contains  the  process  ID  of  the  process  that  is  using  the 
device.  (If  the  device  is  not  being  used,  V.BUSY  contains  a  zero.) 
The  process  ID  is  used  by  SCF  to  prevent  more  than  one  process 
from  using  the  device  at  the  same  time.  V.BUSY  is  defined  by 
SCF. 

SCF  De«lee  Dxi^r  Siilteeotaibaes 

Like  all  device  drivers,  SCF  device  drivers  use  a  steindard  esse- 
cutable  memory  module  format. 

The  execution  offset  address  in  the  module  header  points  to  a 
branch  table  that  has  six  3-byte  entries.  Each  entry  is  typically 
an  LBRA  to  the  corresponding  subroutine.  The  branch  table  is 
deCtzied  as  idlomt 
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ENTRY 


LBRA 
LBRft 
LBRA 
LBRA 
LBRA 
LBRA 


GETSTA 
SETSTA 
TERM 


I  NIT 
READ 

WRITE 


Initialize  driver 
Read  character 
Write  character 
Get  status 
Set  status 
Terminate  device 


If  no  error  occurs,  each  subroutine  exits  with  the  C  bit  in  the 
Condition  Code  Register  cleared.  If  an  error  occurred,  each  sub- 
routine sets  the  C  bit  and  returns  an  appropriate  error  code  in 

Register  B. 

The  rest  of  this  chapter  describes  these  subroutines  and  their 
entry  and  &sit  conditions. 
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Init  Initializes  device  control  registers,  and 
enables  interrupts  if  necessary. 

Entry  Conditions: 

Y      =  address  of  the  device  descriptor 
U     =  address  of  the  device  rmmcry  arm 

Exit  Conditions: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  Prior  to  being  called,  the  device  memory  area  is  cleared  (set 
to  zero),  except  for  V.PAGE  and  V.PORT.  (V.PAGE  and 
V.PORT  contain  the  device  address.)  There  is  no  need  to 
initialize  the  part  of  the  memory  area  used  by  the  I/O 
manager  and  SCF. 

•  Mbw  these  steps  to  use  Init: 

1.  Initialize  the  device  memory  area. 

2.  Place  the  IRQ  service  routine  on  the  IRQ  polling  list, 

using  the  Set  IRQ  system  call  (F$IRQ). 

3.  Initialize  the  device  control  registers. 
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Read  Beads  the  next  cliaracter  from  the  input 
buffer. 


Entry  Conditions: 

Y      =  address  of  the  path  descriptor 
li     =  address  of  the  (hvice  meimry  area 

Exit  Conditions: 

A      =  character  read 
CG    =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  This  is  a  step  by  step  description  of  a  Read  operation: 

1.  Read  gets  the  next  character  from  the  input  buffer. 

2.  If  no  data  is  ready,  Read  copies  its  process  ID  from 
V.BUSY  into  V.WAKE.  It  then  uses  the  Sleep  syBtem 
call  to  put  itself  to  sleep. 

3.  Later,  when  Read  receives  data,  the  IRQ  service  rou- 
tine leaves  the  data  in  a  buffer.  Then,  the  routine 
checks  V.WAKE  to  see  if  any  process  is  waiting  for  the 
device  to  complete  I/O.  If  so,  the  IRQ  service  routine 
sends  a  wakeup  signal  to  the  waiting  process. 

•  Data  buffers  are  not  automatically  allocated.  If  a  buffer  is 
used,  it  defines  it  in  the  device  memory  area. 
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W^lt6  Sends  m  tihsttmksr  (pades  m  In 

an  output  buffer)  and  enables  tibie  device 
output  interrupts. 

Entry  Conditions: 

A      =  character  to  write 

Y      =  address  of  the  path  descriptor 

U     =  address  of  the  device  ta&nwy  area 

Exit  Conditions: 

CC  =  carry  set  on  error 
B     =  error  code  (if  any  ) 

•  If  the  data  buffer  is  full,  Write  copies  its  process  ID  from 
V.BUSY  into  V.WAKE.  Write  then  puts  itself  to  sleep. 

Later,  when  the  IRQ  service  routine  transmits  a  character 
and  makes  room  for  more  data,  it  checks  V.WAKE  to  see  if 
there  is  a  process  waiting  for  the  device  to  complete  I/O.  If 
there  is,  the  routine  sends  a  wakeup  signal  to  f&t  process. 

•  Write  must  ensure  that  the  IRQ  sa*vice  routine  that  starts 

it  begins  to  place  data  in  the  buffer.  After  an  interrupt  is 
generated,  the  IRQ  service  routine  continues  to  transmit 
data  until  the  data  buffer  is  empty.  Then,  it  disables  the 
device's  ready-to-transmit  interrupts. 

•  Data  buffers  are  not  allocated  automatically.  If  a  buffer  is 
used,  define  it  in  the  device  memory  area. 
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Getsta  and  Setsta 

Gets/sets  device  operating  parameters  (status)  as 
specified  for  the  Get  Status  and  Set  Status  system 
calls.  Getsta  and  Setsta  are  wildcard  calls. 

Entry  Conditions: 

A      =  depends  on  the  function  code 
Y      =  address  of  the  path  descriptor 
U     =  address  of  the  device  memory  area 
Other  registers  depend  on  the  function  code. 

Exit  Conditions: 

B  =  error  code  (if  any) 
CC  =  carry  set  on  error 
Other  registers  depend  on  the  function  code 

Additional  Information: 

•  Any  codes  not  defined  by  the  I/O  manager  or  SCF  are 

passed  to  the  device  driver. 

•  You  might  need  to  examine  or  change  the  register  stack 
that  contains  the  values  of  the  6809  registers  at  the  time  of 
the  call.  The  address  of  the  register  stack  can  be  found  in 
PD.RGS,  which  is  located  in  the  path  descriptor. 

•  Yaa  can  use  the  following  offsets  to  access  any  value  in  the 
regist^  packet: 

Relative  Size 


Name  Address  (Bytes)      6809  Register 


R$CC 

$00 

1 

Condition  Codes  Register 

R$D 

$01 

0 

Register  D 

R$A 

$01 

1 

Register  A 

R$B 

$02 

1 

Itegister  B 

R$DP 

$03 

1 

Register  DP 

R$X 

$04 

2 

Register  X 

R$Y 

$06 

2 

Register  Y 

R$U 

$08 

2 

Register  U 

R$PC 

SO  A 

2 

Program  Counter 

The  function  code  is  retrieved  from  the  R$B  on  the  user  stack. 


6-15 


0&-9  Ibchnical  Reference 


Term  Terminates  a  device.  Term  is  called  when  a 
device  is  no  longer  in  use  (when  the  link 
count  of  the  device  descriptor  module 
becomes  zero). 

Entry  CqxidiliQiis; 

U     =  pointer  to  the  device  memory  area 

Exit  Conditions: 

GC  =  carry  set  on  error 
B     =  error  code  (if  any) 

Additional  Information: 

•  To  use  Term: 

1.  Wait  until  the  ERQ  service  routine  empties  the  out|jut 
buffer. 

2.  Disable  the  device  interrupts. 

3.  Remove  the  device  from  the  IRQ  polling  list. 

•  When  Term  closes  the  last  path  to  a  device,  OS-9  returns 
to  the  memory  pool  the  memory  that  the  device  used.  If  the 
device  has  been  attached  to  the  system  using  the  I$Attach 
system  call,  OS-9  does  not  return  the  static  storage  for  the 
driw  until  an  IfDetach  call  is  made  to  the  §sm.m.  Mod- 
ules contained  in  the  Boot  file  are  never  terminated,  esven  if 
their  link  counts  reach  0. 
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IRQ  Service  Bcmtine 

Receives  device  interrupts.  When  I/O  is  complete,  the 
routine  sends  a  wakeup  signal  to  the  process  identi- 
fied by  the  process  ID  in  V.WAKE.  The  routine  also 
clears  V.WAKE  as  a  flag  to  indicate  to  the  main  pro- 
gram that  the  IRQ  has  occurred. 


Additionid  Ixifmniitiaiil 

•  The  IKQ  Service  Routine  is  not  included  in  device  driver 
branch  tables,  and  is  not  called  directly  by  SCF.  However,  it 

is  a  key  routine  in  device  drivers. 

•  When  the  IRQ  Service  routine  finishes  servicing  an  inter- 
rupt, the  routine  must  clear  the  carry  and  exit  with  an 
RTS  instruction. 

•  Here  is  a  typical  sequence  of  events  that  the  IRQ  Service 
Routine  performs: 

1.  Service  the  device  interrupts  (riecelve  data  from  the 
device  or  send  data  to  it).  Ensure  this  routine  puts  its 
data  into  and  get  its  data  from  buffers  that  are  defined 
in  the  device  memory  area. 

2.  Wake  up  any  process  that  is  waiting  for  I/O  to  complete. 
To  do  this,  the  routine  checks  to  see  if  there  is  a  pro- 
cess ID  in  V.W\KE  (a  value  other  than  zero);  if  so,  it 
sends  a  wakeup  signal  to  that  process. 

3.  If  the  device  is  ready  to  send  more  data,  and  the  output 
buffer  is  empty,  disable  the  device's  ready-to-transmit 
interrupts. 

4.  If  a  pause  character  Ii  received,  set  V.PAUS  in  the 
attached  device  storage  area  to  a  value  other  than  zero. 
The  address  of  the  attached  device  memory  area  is  in 
V.DEV2. 

V.PAUS  in  the  attached  device  storage  area  to  non-zero 
value.  The  address  of  the  attached  device  memory  area 
is  in  V.DEV2. 

5.  If  a  keyboard  terminate  or  interrupt  character  is 
received,  signal  the  itfocess  in  V.LPRC  (last  known 
process)  if  any. 
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The  Pipe  File  Manager 
(PIPEMAN) 


The  Pipe  file  manage  handles  control  of  processei  that  use 
paths  to  pipes.  Pipes  allow  concurrently  executing  processes  to 
send  each  other  data  by  using  the  output  of  one  process  (the 
writer)  as  input  to  a  second  process  (the  reader).  The  reader  gets 
input  from  the  standard  input.  The  exclamation  pdnt  (!)  opera- 
tor specifies  that  the  input  or  output  is  from  or  to  a  pipe.  The 
Pipe  file  manager  allocates  a  256-byte  block  and  a  path  descrip- 
tor for  data  transfer.  The  Pipe  file  manager  also  determines 
which  process  has  control  of  the  pipe.  The  Pipe  file  manager  has 
the  stajidard  file  manager  branch  table  at  its  entry  point: 

Pipelnt     Ibra  Create 
Ibra  Open 
Ibra  MakDir 
Ibra  ChgDir 
Ibra  Delete 
Ibra  Seek 
Ibra  PRead 
Ibra  PWrite 
Ibra  PRdLn 
Ibra  PWrLn 
Ibra  Getstat 
Ibra  Putstat 
Ibra  Close 

You  cannot  use  MakDir,  ChgDir,  Delete,  and  Seek  with  pipes.  If 
you  try  to  do  so,  the  system  returns  E$UNKSVC  (unknown  ser- 
vice request).  Getstat  and  Putstat  are  also  no-action  service  rou- 
tines. They  return  without  error. 

Create  and  Open  perform  the  same  functions.  They  set  up  the 
256-byte  data  exchange  buffer,  and  save  several  ad^esses  in  the 
path  descriptor. 

The  Close  request  checks  to  see  if  any  process  is  reading  or  writ- 
ing through  the  pipe.  If  not,  OS-9  returns  the  buffer. 

PRead,  PWrite,  PRdLn,  and  PWrLn  read  data  from,  the  buffer 
and  write  data  to  it. 
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The  !  operator  tells  the  Shell  that:  froesss^  wish  to  communicate 
through  a  pipe.  For  example: 

prod    !    proc2  |  ENTER  | 

In  tliis  example,  shell  forks  Procl  with  the  standard  output  path 
to  a  aalL  fe^ks  Proc2  with  the  itaaa&fd  iapit  pith  from  a 
pipe. 

Shell  can  also  handle  a  series  of  {arocesses  umng  p^es.  Example: 
prod    !  proei  !  proe3  !  proc4  | BfliR  1 

The  following  outline  shows  how  to  set  up  pipes  between 

processes: 


Open  /pipe 

save  path   in  variable  x 

Dup  path  #1 

save   stdout    in  variable  y 

Dup  X 

make  path  available 

Fork  prod 

put   pipe  in  stdout 

(Dup  uses   lowest  available) 

Close  #1 

make  path  available 

Dup  y 

restore  stdout 

Close  y 

make  path  available 

Dup   path  *B 

save  stdin  in  Y 

Close  #0 

make  path  available 

Dup  X 

put  pipe  in  stdin 

Fork  2 

fork  proeess  i 

Close  #0 

make  path  available 

Dup  y 

restore  stdin 

Close  X 

no    longer  needed 

Close  y 

no  longer  needed 
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Example:  The  following  example  shows  how  an  application  can 
initiate  another  process  with  the  stdin  and  stdout  routed 
through  a  pipe. 


Open  /pi pel 
Open  /pipe2 
Dap  0 
Dup  1 
Close  0 
Close  1 
Dup  a 
Dup  b 
Fork 


save 
save 
save 
save 
ma  k  e 
ma  k  e 
ma  k  e 
ma  k  e 
new  process 
Close  0  make 
Closel  make 
Dupx  restore 
Dupy  restore 
Return  aSb 


path  in  variable  a 

path    in  variable  b 
stdin   in  variable  x 
stdout    in  variable  y 
path  available 
path  available 
pipe1  stdin 
pipe2  stdout 


path  available 
path  available 
stdin 
s  t  dout 


return  pipe  path  numbers  to  caller 
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System  Calls 


System  calls  are  used  to  communicate  between  the  OS-9  operat- 
ing system  and  assembly-language  programs.  Inhere  are  two 
major  types  of  calls — I/O  calls  and  function  calls. 

Function  calls  include  user  mode  calls  and  system  mode  calls. 

Each  system  call  has  a  mnemonic  name.  Names  of  I/O  calls  start 
with  1$.  For  example,  the  Change  Directory  call  is  I$ChgDir. 
Names  of  function  calls  start  with  F$.  For  example,  the  Allocate 
Bits  call  is  F$AllBit.  The  names  are  defined  in  the  assembler- 
input  conditions  equate  file  called  0S9Defs. 

I^stem  mode  calls  are  privileged.  You  can  execute  them  only 

while  OS-9  is  in  the  system  state  (when  it  is  processing  another 
system  call,  executing  a  file  manager  or  device  driver,  and  so 
on). 

System  mode  calls  are  incluited  In  lMs  manual  primarily  for  pro- 
grammers writing  device  drivers  and  other  system-level 
applications. 

CaUing  Procedure 

To  execute  any  system  calls,  you  need  to  use  an  SWI2 

instruction: 

1.  Load  the  6809  registers  with  any  appropriate  parameters.' 

2.  Execute  £in  SWI2  instruction,  followed  immediately  by  a  cmr 
stant  hyte,  which  is  the  request  code.  In  the  references  in 

this  chapter,  the  first  line  is  the  system  call  name  (for  exam- 
ple Close  Path)  and  the  second  line  contains  the  call's  mne- 
monic name  (for  example  I$Close),  the  softwiff©  toterrupt 
Code  2  (103F),  and  the  call's  request  code  (for  example,  8F) 
in  hsEailecimeii. 

3.  After  OS-9  processes  the  call,  it  returns  any  parameters  in 

the  6809  registers.  If  an  error  occurs,  the  C  bit  of  the  condi- 
tion code  register  is  set,  and  Register  B  contains  the  appro- 
priate error  code.  This  feature  permits  a  BCS  or  BCC 
instruction  immediately  following  the  system  call  to  branch 
eitha:  if  iheaee  is  an  error  or  if  no  mem  oecurs. 
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As  an  example,  hare  is  the  Close  system  call: 

LDA  PATHNUM 
SMI2 

FCi  $8F 
BCS  ERROR 

You  can  use  the  assembler's  0S9  directive  to  simplify  the  call,  as 
follows. 

LDA  PATHNUM 
0S9  UClose 
BCS  ERROR 

The  ASM  assembler  allows  any  combination  of  upper-  or  lower- 
case letting.  The  SMA  assemMei^,  included  in  the  OS-9  Level 

Two  Development  Pak,  is  case  sensitive.  The  names  in  this  man- 
ual have  been  spelled  with  upper  and  lower  case  letters,  match- 
ing the  defs  for  RMA. 

I/O  System  Calls 

OS-9's  I/O  calls  are  easier  to  use  than  many  other  systems'  I/O 
calk.  T%ds  is  beeatise  the  calling  program  does  not  Jtove  to  allo- 
cate and  set  up  file  control  blocks,  sector  biff^rs,  and  so  on. 

Instead,  OS-9  returns  a  1-byte  path  number  whenever  a  process 
opens  a  path  to  a  file  or  device.  Until  the  path  is  closed,  you  can 
use  this  path  number  in  later  I/O  requests  to  identify  the  file  or 
device. 

In  addition,  OS-9  allocates  and  maintains  its  own  data  struc- 
tures; so,  you  need  not  deal  with  them. 

System  Call  Descriptions 

The  rest  of  this  chapter  consists  of  the  system  call  descriptions. 
At  the  top  of  each  description  is  the  system  call  name,  followed 
by  its  mnemonic  name,  the  SWI2  code  and  the  request  code. 
Next  are  the  call's  entry  and  exit  conditions,  followed  by  addi- 
tional information  about  the  code  where  appropriate. 

In  the  system  call  descriptions,  registers  not  specified  as  entry 
or  exit  conditions  are  not  altered.  Strings  passed  as  parameters 
are  normally  terminated  with  a  space  character  and  end-of-line 
charact^,  or  with  Bit  7  of  the  last  character  set. 
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If  an  error  occurs  on  a  system  call,  the  C  bit  of  Register  CC  is 
set,  and  Register  B  contains  the  error  code.  If  no  error  occurs, 
the  C  bit  is  clear,  and  Register  B  contains  a  value  of  zero. 

User  Mode  System  Calls  Quick  Reference 

Following  is  a  summary  of  the  User  Mode  System  Calls  refer- 
enced in  this  chapter: 


r  !p  Alliilt 

Sets  bits  in  an  allocation  bit  map 

Chains  a  process  to  a  new  module 

r  jJ>L/mprNaiii 

Compares  two  names 

b  {jjCpyMem 

Copies  external  memory 

Generates  a  cyclic  redundancy  check 

1 5>Uelr$it 

Deallocates  bits  in  an  allocation  bit  map 

V  ^iLXlt 

Terminates  a  process 

F$Fork 

Starts  a  new  process 

F$GBlkMp 

Gets  a  copy  of  a  system  block  map 

F$GModDr 

Gets  a  copy  of  a  module  directory 

FSGPrDsc 

Gets  a  copy  of  a  process  descriptor 

FfRTrnt 

Spts  a  ftipmfll  iTitpropnt  traTi 

r  !t>iU 

Returns  a  process  ID 

F$Link 

Links  to  a  memory  module 

F$Load 

Loads  a  module  from  mass  storage 

F$Mem 

Changes  a  process's  data  area  gj^i 

F$NMT.ink 

Links  to  a  module;  does  mt  ma^  ihe  mod- 

ule into  the  user's  address  space 

F$NMLoad 

Loads  a  module  but  does  not  map  it  into  the 

user's  address  space 

F$Perr 

Prints  an  error  message 

F$PrsNam 

Parses  a  pathlist  name 

F$SchBit 

Searches  a  bit  map 
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F$Send 

Sends  a  signal  to  a  process 

F$Sleep 

Suspends  a  process 

F$SPrior 

Sets  a  process's  priority 

jF$SSWI 

Sets  a  software  intmupt  vector 

F$STiitte 

Sets  the  system  time 

F$SUser 

Sets  the  user  ID  number 

F$Tinie 

Returns  the  current  time 

F$UiiLink 

Unlinks  a  module 

F$UnLoad 

Unlinks  a  module  lay  name 

F$Wait 

Waits  for  a  signal 

I$Attacli 

Attaches  an  I/O  device 

I$Chgdir 

Changes  a  working  directory 

I$Close 

Closes  a  path 

I$Create 

Creates  a  new  01e 

I$Delete 

Deletes  a  file 

I$DeIetX 

Ddetes  a  file  from  the  execution  directory 

I$Detach 

Detaches  an  I/O  device 

I$Dup 

Duplicates  a  path 

Gets  a  device's  status 

XSiXakDir 

Creates  a  directory  file 

I$Open 

Opens  a  path  to  an  existing  file 

I$Read 

Reads  data  from  a  device 

I$R^HlLn 

Reads  a  line  of  data  from  a  device 

I$Seek 

Positions  a  file  pointer 

I$SetStt 

Sets  a  device's  status 

I$Write 

Writes  data  to  a  device 

I$WritLn 

Writes  a  data  line  to  a  device 
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System  Mode  Calls  Quick  Reference 

Following  is  a  summary  of  the  System  Mode  Calls  reSssemed  in 

this  chapter: 

F$Alarm  Sets  up  an  alarm 

F$A1164  Allocates  a  64-byte  memory  block 

F$A11HRAM  Allocates  high  RAM 

F$AlIImg  Allocates  image  RAM  blocks 

F$AllPrc  Allocates  a  process  descriptor 

F$A11RAM  Allocates  RAM  blocks 

F$AllTsk  Allocates  a  process  task  number 

F$AProc  Enters  active  process  queue 

F$Boot  Performs  a  system  bootstrap 

F$BtMem  Performs  a  memory  request  bootstrap 

F$ClrBlk  Clears  the  specified  block  of  memory 

F$DATLog  Converts  a  DAT  block  offset  to  a  logical 
address 

F$DelIing  Deallocates  image  RAM  blocks 

F$DelPrc  Deallocates  a  process  descriptor 

F$DelRAM  Deallocates  RAM  blocks 

F$DelTsk  Deallocates  a  process  task  number 

FfELink  Links  modules  using  a  module  directory 

entry 

F$FModul  Finds  a  module  directory  entry 

F$Find64  Finds  a  64-byte  memory  block 

F$FreeHB  Gets  a  free  high  block 

F$FreeLB  Gets  a  free  low  block 

F$GCMDir  Compacts  module  directory  entries 

F$GProcP  Gets  a  process's  pointer 
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F$IODel 

Deletes  an,  moAri© 

F$IOQu 

Puts  an  eiria^  tail  an  I/O  queue 

F$IRQ 

Makes  an.  entry  into  IRQ  polling  table 

F$LDABX 

Loads  Register  A  from  0,X  in  Task  B 

F$LDAXY 

Loads  A[X,[Y]] 

F$LDDDXY 

Loads  D[D+X,rY]] 

F$MapBIk 

Maps  Hm  ^d&d  lakdk 

F$Move 

Moves  data  to  m  Affiiittt  address  space 

F$NProc 

Starts  &e  next  process 

F$ReITsk 

ReLeasm  a  task  number 

F$BesTsk 

'Reaemm  t  ttml^ 

F$Ret64 

Retumt  a  64-byte  memory  block 

F$SetImg 

Sets  a  process  DAT  image 

F$SetTsk 

Sets  a  proi^s's  task  DAT  registers 

F$SLink 

Performs  a  system  link 

F$SRqMem 

Performs  a  9Bt@m  memmy  m^iamt 

F$SRt]Mtem 

Performs  a  system  memory  return 

lIlbbcLlib  cL  lUnLLlUIl  rcqucbl 

F$STABX 

Stores  Register  A  at  0,x  in  Task  B 

F$VIBQ 

Makes  an  entry  in  a  virtual  IRQ  polling 

table 

F$VModul 

%lidates  a  modtie 

841 
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User  Syst^  Calls 


Allocate  Bits  Sets  bits  in  sin 

0S9  F$AUBit  103F  13  alkicate  Ml  ttiap 

Entry  Conditions: 

D      =  number  of  the  first  bit  to  set 

X     =  starting^  addri^ss  of  the  allocation  bit  map 

Y     =  number  df  Mts  to  mt 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  Bit  numbers  range  from  0  to  ra-i,  where  n  is  the  number  of 
bits  in  the  allocation  bit  map, 

•  Warning:  Do  not  issue  the  Allocate  Bits  call  with  Register 
Y  set  to  0  (a  bit  count  of  0). 
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Chain 

OS9  F$Cham  103F  05 

Entry  Conditions: 

A 
B 

X 
Y 

U 

Error  Output: 

CC  =  carry  set  on  error 
B     =  &ror  code  (if  any) 

Additional  Information: 


Loads  and  executes  a 
new  primary  module 
without  creating  a  new 
process 


=  language/type  code 

=  me  (f  the  data  area  (in  pages);  must  be  at  least  one 

=  axUress  of  the  moduh  name  orflksname 
=  parameter  area  size  (in  l^es);  de&ults  to  zero  if  not 
specified 

=  starting  address  of  the  parameter  arm 


•  Chain  loads  and  executes  a  new  primary  module,  but  does 
not  create  a  new  process.  A  Chain  system  eall  is  siniilar  to 
a  R)rk  foltowed  by  ein  Exit,  but  it  has  less  processing  over- 
head. Chain  resets  the  calling  process  program  and  data 
memory  areas  and  begins  executing  a  new  primary  module. 
It  does  not  affect  open  paths.  This  is  a  user  mode  system 
call. 

•  Warning:  Make  sure  that  the  hardware  stack  pointer  (Reg- 
istrar SP)  is  located  in  the  direct  page  before  Chain  exe- 
cutes. Otherwise  the  system  might  crash  or  return  a 
suicide  attempt  error.  This  precaution  also  prevents  a  sui- 
cide in  the  event  that  the  new  module  requires  a  smaller 
data  area  than  that  in  use.  Allow  approximately  200  bytes 
of  stack  space  for  execution  of  the  Chain  system  call. 

•  Chain  performs  the  following  steps: 

1.  It  causes  OS- 9  to  unlink  the  process's  old  primary 
modtile. 
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2.  OS-9  parses  the  name  string  of  the  new  process's  pri- 
mary module  (the  program  that  is  to  be  executed  first). 
Then,  it  causes  OS-9  to  search  the  system  module 
directory  to  see  if  a  module  with  the  same  name,  typey 
and  language  is  already  in  memory. 

S.   If  the  module  is  In  memory,  ft  links  to  it.  If  the  modtile 

is  not  in  memory,  it  uses  the  name  string  as  the  path- 
list  of  a  file  to  load  into  memory.  Then,  it  links  to  the 
first  module  in  this  file.  (Several  modules  can  he  loaded 
from  a  single  file.) 

4.  It  reconfigures  the  data  memory  area  to  the  size  speci- 
fied in  the  new  primary  module's  header. 

5.  It  intercepts  and  erases  any  pending  signals. 

The  following  diagram  shows  how  Chain  sets  up  the 
data  meanory  area  and  registers  for  the  new  module. 


Parameter  Area 


Y  (highest  address) 
X,SP 


Data  Area 


Direct  Page 


-  U,DP  (lowest  address) 

D     =  parameter  area  size 

PC    =  module  entry  point  absolute  address 
CC    =  F  =  0,  1  =  0;  others  are  undefined 

Registers  Y  and  U  (the  top-of-memory  and  bottom-of-memory 
pointers,  respectively)  always  have  values  at  page  boundaries*  If 
the  parent  process  does  not  specify  a  size  for  the  parameter  area, 
the  size  (Register  D)  defaults  to  zero.  The  area  must  be  at 
least  one  page  long. 

(Bbr  more  information,  see  the  Ibrk  system  call.) 
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0S9F$€mpNam  103P  11 

Entry  Conditions: 

B      =  length  ofstringl 
K     =  oMress  ^  strmgl 
Y     =  address  of  string2 

Exit  Vm^Ummi 
cc 

Additional  Information: 


tor  a  match 


=  carry  clear  if  the  strfags  mateh 


•  The  Compare  Names  call  compares  two  strings  and  indi- 
cates 'witether  they  match.  TDse  this  call  -wlih  the  "Psem 
Name  system  call.  The  second  string  must  have  the  most 
significant  bit  (Bit  7)  of  the  last  character  set. 
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Copy  External 
Memory 

0S9  F$CpyMem 
103P  IB 

Entry  Conditions: 

D  =  DAT  image  pointer 

X  =  offset  in  block  to  begin  copy 

Y  =  &yte  count 

U  =  caller^  desUnatkm 

Error  Output: 

CC    =  C  bit  set  on 

B      =  appropriate  error  code 

Additional  Information: 

•  You  can  view  any  system  jn^nory  through  the  use  of  the 
Copy  Ext^Pnal  Memory  call.  Tto  call  assimtes  X  is  the 
address  of  the  64K  space  described  by  the  DAT  image 

given. 

•  If  you  pass  the  entire  DAT  image  of  a  process,  place  a  value 
in  the  X  Reprter  that  equals  the  address  in  the  process 
space.  If  you  pa^  a  partial  DAT  image  (the  U]^^  halfi, 
then  place  a  vmlue  in  Register  X  equals  the  onset  ten 
the  begimiing  of  the  DAT  ima^  ($ft9Q0f . 

•  The  support  module  for  this  caU  is  OS9p2. 


Reads  external  memory 
into  the  user's  buffer 
for  Inspection 
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CRC 

OS9  F$CRC  103F  17 

Entry  Conditioiis: 

X 
Y 
U 

Exit  Conditions: 

Updates  the  CRC  accumulator. 

Additional  Information: 


Calculates  the  CRC  of 
a  module 


=  starting  byte  address 
=  mimher  bytes 

=  address  of  the  3-byte  CRC  accumulator 


•  The  CRC  call  calculates  the  CRC  (cyclic  redundancy  count) 
for  use  by  compilers,  assemblers,  or  other  module 
generators. 

•  The  calculation  begins  at  the  starting  byte  address  and  con- 
tinues over  the  specified  number  of  bytes. 

•  You  need  not  cover  an  entire  module  in  one  call,  since  the 
CRC  can  be  accmnulated  m&t  several  calls.  The  CRC  accu- 
mulator can  be  any  3-byte  memory  area.  You  must  initial- 
ize it  to  $FFFFFF  before  the  first  CRC  call. 

•  When  checking  an  existing  module  CRC,  the  calculation 
should  be  performed  on  the  entire  module  (including  the 
module  CRC),  The  CRC  accumulator  will  contain  the  CRC 
consteBt  biytes  if  ibe  modde  CRC  is  wemc^ 

•  If  the  CRC  of  a  new  module  is  to  be  generated,  the  CRC  is 

accumulated  over  the  module  (excluding  CRC).  The  accu- 
mulated CRC  is  complemented  then  stored  in  the  correct 
position  in  the  module. 

•  Be  sure  to  initialize  the  CRC  aecxmiulator  only  once  for 
each  module  checked  by  CRC. 
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Deallocate  Bits       CTtim,tB  allocation  tlm& 

OS9  F$DelBit  103F  14 

Entry  Conditions: 

D      =  number  of  the  first  bit  to  set 

X      =  starting  address  of  the  allocation  bit  map 

Y      =  number  of  bits  to  set 

Exit  Conditions:  None 

Additional  Information: 

•  The  Deallocate  Bits  call  clears  bits  in  the  allocation  bit 
map  pointed  to  by  Register  X.  Bit  numbers  are  in  the 
range  0  to  n-1,  where  n  is  the  number  of  bits  in  the  alloca- 
tion bit  map. 

•  Warning:  Do  not  call  Deallocate  Bits  with  Register  Y  set 
to  0  (a  bit  count  of  0). 
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Exit 


Termiixate  the  calliiig 
process 


OS9  F$E3dt  103F  06 


Entry  Conditions: 

B      =  status  code  to  return  to  the  parent 

Exit  Conditions: 

The  process  is  tmninated. 

Additional  Information: 

•  The  Exit  system  call  is  the  only  way  a  process  can  termi- 
nate itself.  Exit  deallocates  the  process's  data  memory 
area,  and  unlinks  the  process's  primary  module.  It  also 
cimm  all  cf  @a  paths  autj^mtieally. 

•  The  Wait  system  call  always  returns  to  the  parent  the  sta:- 

tus  code  passed  by  the  child  in  its  Exit  call.  Therefore,  if 
the  parent  executes  a  Wait  and  receives  the  status  code,  it 
knows  the  child  has  died.  This  is  a  user  mode  system  call. 

•  Exit  unlinks  only  the  primary  module.  Unlink  any  module 
that  is  loaded  or  linked  to  by  the  process  before  calling 


E^t. 
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Fork  Creates  a  child  process 

OS9  F$Fbrk  103F  03 

Entry  Conditions: 

A     =  langxiage/type  code 
B      =  size  of  the  optional  duta,  amt  (iDi  pages) 
X     =  address  of  the  module  name  or  filmame  (See  the  follow- 
ing example.) 

Y     =  size  of  the  parameter  area  (in  pages);  defeults  to  zero  if 
not  specified 

U     =  starting  address  <ef  the  paraimter  arw^  mast  be  at 
least  one  page 

E3^  CoQdite&s: 

X      =  aMress  of  the  last  byte  of  the  mme  +  1  (#ee  tM  fol- 
lowing example.) 
A      =  new  process  10  number 

Error  Output: 

B  =  error  code  (if  any) 
CC    =  carry  set  on  error 

Additional  Informalion: 

•  Bbrk  creates  a  new  process,  a  chiM  of  th©  calling  process. 
Fork  also  sets  up  the  child  process's  memory  and  6809  reg- 
isters and  standard  I/O  paths. 


•  Before  the  Fork  call: 


T 

E 

S 

T 

$0D 

♦ 

X 
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After  the  Fork  call: 


T 

E 

S 

T 

$0D 

♦ 

X 

This  is  the  seipence  of  fbrk's  qierations: 

1.   OS-9  Tpai*ses  the  name  sMng  of  the  new  pt«cess*s  |Hi- 

mary  module  (the  program  that  OS-9  executes  first). 
Then,  it  searches  the  system  module  directory  to  see  if 
the  program  alreatfy  is  ia  memory. 

2a.  The  next  step  depends  on  whether  or  not  the  program  is 
already  in  msmory.  If  the  program  is  in  memmy,  OS-9 
Itotks  the  moinle  to  the  process  &S.  @sieilei  it, 

b.  If  the  program  is  not  in  mranory,  08-9  uses  the  name 
as  the  pathlist  of  the  file  that  is  to  be  loaded  into  mem- 
ory. Then,  the  first  module  in  this  file  is  linked  to  and 
executed.  (Several  modules  can  be  loaded  from  one  file.) 

3.  OS-9  uses  the  primary  module's  header  to  determine 
the  initial  size  of  the  process's  data  area.  It  then  tries 
to  allocate  a  contiguous  RAM  area  of  that  size.  (This 
area  includes  the  parameter  passing  area,  which  is  cop- 
ied from  the  parent  process's  data  area.) 

4.  The  new  process's  data  memory  area  and  registers  are 
set  up  as  shown  in  the  following  diagram.  OS-9  uses 
the  execution  offset  given  in  the  module  header  to  set 
the  program  counter  to  the  module's  entry  point. 


Parameter  Area 


Data  Area 


Direct  P&ge 


X,SP  (highest  address) 


U,DP  (lowest  address) 
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D      =  size  of  the  parameter  area 

PC    =  module  entry  point  absolute  address 

CC    =  F=0, 1  =  0,  o^r  condition  code  flags  are  undefined 

Registers  Y  and  U  (the  top-of-memory  pointer  and  bottom- 
of-memory  pointer,  respectively)  always  have  values  at  page 
boundaries. 

As  stated  earlier,  if  the  parent  does  not  specify  the  size  of 
the  parameter  area,  the  size  defaults  to  zero.  The  minimum 

overall  data  area  size  is  one  page. 

When  the  shell  processes  a  command  line,  it  passes  a 
string  in  the  parameter  area.  This  string  is  a  copy  of  the 
parameter  part  of  the  command  line.  To  simplify  string- 
oriented  processing,  the  shell  also  inserts  an  end-of-line 
character  at  the  end  of  the  parameter  staring. 

Register  X  points  to  the  start  byte  of  the  parameter  string. 
If  the  command  line  includes  the  optional  memory  size 
specification  (#n  or  #nK),  the  shell  passes  that  size  as  the 
requested  memory  size  when  executing  the  Fbrk. 

•  If  any  of  the  preceding  operations  is  unsuccessful,  the  Ebrk 
is  terminated  and  OS-9  returns  an  error  to  the  caller. 

•  The  child  and  parent  processes  execute  at  the  same  time 
unless  the  parent  executes  a  Wait  system  call  immediately 
after  the  Fork.  In  this  case,  the  parent  waits  until  the  child 
$3&B  ibttoe  It  regimes  esse^tiMmi.  . 

•  Be  careful  when  recursively  calling  a  program  that  uses 

the  Fork  system  call.  Another  child  can  be  created  with 
each  new  execution.  This  continues  until  the  process  table 
becomes  full. 

•  Do  not  fork  a  process  with  a  memory  size  of  0. 
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Get  it^m 


Gets  a  eopf  of  the 
system  block  map 


010  F$GBUsMp  103F  19 

Entry  Gosiditions: 

X     =  pointer  to  the  1024 -byte  buffer 

D     =  number  of  bytes  per  block  ($2000)  (MMU  block  size 

dependent) 
Y     =  system  menmy  bheh  sli® 

Error  Output: 

CC  =  ceirry  set  on  &ror 
B     =  error  code  (if  any) 

Additional  Information: 

•  The  Get  System  Block  Map  call  copies  the  system's  metnoty 
block  map  into  the  aset'a  brffep  to*  inspection.  The  C^l 
MFREE  command  Uses  this  call  to  find  out  how  much  fi-ee 

memory  exists. 

•  The  support  module  for  this  call  is  OS9p2. 
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Get  Module 
Directory 


Gets  a  copy  of  the 
system  module 
directory 


F$GModDr  1031' lA 

Entry  Conditions: 

X  =  pointer  to  the  2048 -byte  buffer 
Y  =  end  of  copied  module  directory 
U     =  start  address  of  system  module  directory 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  The  Get  Module  Directory  call  copies  the  system's  module 
directory  into  the  user's  buffer  for  inspection.  The  OS-9 
MDIR  command  uses  this  call  to  read  the  module 
directory. 

•  The  support  module  for  this  call  is  OS9p2. 
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Get  Process 
Descriptor 


Gets  a  copy  of  the 
process's  process 
descriptor 


F$GPrDsc  103F  18 

Entry  Condition^: 

A      =  requested  process  ID 

X      =  pointer  to  a  512 -byte  buffer 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  The  Get  Process  Descriptor  call  copies  a  process  descriptor 
into  the  calling  proc6Ss'fe  btlf&r  for  inspection.  The  data  in 
the  process  descriptor  cannot  be  changed.  The  OS-9  PROCS 
command  uses  this  call  to  get  information  about  each  exist- 
ing procese, 

•  The  support  module  for  this  call  is  OS9p2. 
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Intercept  Sets  a  signal  intercept 

0S9  F$lGpt  103F  09 

Entry  Conditions: 

X      =  address  of  the  intercept  routine 

U      =  starting  address  of  the  routine's  memory  area 

Exit  Conditions: 

Signals  sent  to  the  process  cause  the  intercept  routine  to  be 
called  instead  of  the  process  being  killed. 

Additional  Information: 

•  Intercept  tells  OS-9  to  set  a  signal  intercept  trap.  Then, 
whenever  the  process  receives  a  signal,  OS-9  executes  the 

process's  intercept  routine. 

•  Store  the  address  of  the  signal  handler  routine  in  Register 
X  and  the  base  address  of  the  routine's  storage  area  in 
Register  U. 

•  Once  the  signal  trap  is  set,  OS-9  can  execute  the  intercept 
routine  at  any  time  because  a  signal  can  occur  at  any 
time. 

•  Terminate  the  intercept  routine  with  an  RTI  instruction. 

•  If  a  process  has  not  used  the  Intercept  system  call  to  set  a 
signal  trap,  the  process  terminates  if  it  receives  a  signal. 

•  This  is  the  order  in  which  F$Icpt  operates: 

1.  When  the  process  receives  a  signal,  OS-9  sets  Registers 
U  and  B  as  follows: 

tJ    =  starting  address  of  the  intercept  routine's 

memory  area 
B     =  signal  code  (process's  termination  status) 

Note:  The  value  of  Register  DP  cannot  be  the 
same  as  it  was  when  the  Intercept  call  was 

made. 

2.  After  setting  the  registers,  OS-9  transfers  execution  to 
the  intercept  routine. 
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Get  ID 

OS9  F$ID  103F  OC 

Entry  Conditions: 

None 

Exit  Conditions: 

A      =  process  ID 
Y      =  user  ID 

Additional  Information: 


Return's  a  caller's 
process  ID  and  user  ID 


•  The  process  ID  is  a  byte  value  in  the  range  1  to  255.  OS-9 

assigns  each  process  a  unique  process  ID. 

•  The  user  ID  is  an  integer  from  0  to  65535.  It  is  defined  in 
ths  s^fSteBi  password  file,  and  is  used  by  the  file  security 
system  and  a  few  other  functions.  Several  processes  can 
have  the  same  user  ID. 

•  On  a  single  user  system  (such  as  the  Color  Computer  3), 
the  user  ID  is  inherited  from  CC3go,  which  forks  the  initial 
shell. 
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Link 

OS9F$Lmk  103F  00 


Links  to  a  memory 
module  that  has  the 
specified  name, 
language,  and  type 


Entry  Conditions: 

A      =  type/ language  byte 

X     =  address  of  the  module  name  (See  the  following 
©cample.) 


Exit 

Conditions: 

A 

=  typefianguage  code 

B 

=  attributes  1  revision  level  (if  no  error) 

X 

=  address  of  the  last  byte  of  the  module  name  +  1  (See 

the  following  example.) 

Y 

=  module  entry  point  absolute  address 

U 

=  module  header  absolute  address 

Error  Output: 

CC    =  C  bit  set  if  error  encountered 


Additional  Inforaialion: 

•  The  module's  link  count  increases  by  one  whenever  Link 
references  its  name.  Incrementing  in  this  manner  keeps 
track  of  how  many  processes  are  using  the  module. 

•  If  the  module  requested  is  not  shareable  (not  re-entrant), 
only  one  process  can  link  to  it  at  a  time. 


•  Before  the  Link  call: 


T 

E 

S 

T 

$0D 

♦ 

X 

After  the  Link  call: 

T 

E 

S 

T 

$0D 

4 

X 
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•  This  is  the  order  in  which  the  Link,  call  opwates: 

1.  OS-9  searches  the  module  directory  for  a  module  that 
has  the  specified  name,  language,  and  type. 

2.  If  OS-9  finds  the  module,  the  address  of  the  module's 
header  is  returned  in  Register  U,  and  the  absolute 
address  of  the  module's  execution  entry  point  is 
returned  in  Register  Y.  (This,  ani  ^Scm  ill§f«ation  is 
contained  in  the  module  header.) 

•  If  OS-9  doesn't  find  the  module — or  if  the  type/language 
codes  in  the  entry  and  exit  conditions  don't  match — OS-9 
returns  one  of  the  following  errors: 

•  Module  not  found 

•  Module  busy  (not  shareable  and  in  use) 

•  Incorrect  or  defective  module  header 


8-24 


User  System  Calls  I  8 


Load  Loads  a  module  or 

Om  FHoad         01  modules  from  a  file 

Entry  Conditions: 

A      =  language/ type  code;  0  =  any  language/tjrpe 
X      =  address  of  the  pathlist  (filename)  (See  the  following 
^cample.) 

Exit  Conditions: 

A      =  language/type  code 

B      =  attributes  I  revision  level  (if  no  error) 

X     =  address  of  the  last  byte  of  the  pathlist  (filename)  +  1 

(See  the  following  example.) 
Y      =  primary  module  entry  point  address 
U      =  address  of  the  module  header 

Error  Output: 

CG    =  carry  set  if  wror  encountered 

Additional  Information: 

•  The  Load  call  loads  one  or  more  modules  from  the  file  spesc?- 
ified  by  a  complete  pathlist  or  from  the  working  execution 
directory  (if  an  incomplete  pathlist  is  given). 

•  The  file  must  have  the  execute  access  mode  bit  set.  It  also 
must  contain  one  or  more  with  propOT  module  h^ers. 

•  OS-9  adds  all  modules  loaded  to  the  system  module  direc- 
tory. It  links  the  first  module  read.  The  exit  conditions 
apply  only  to  the  first  module  loaded. 

•  Before  the  Load  call: 


/ 

D 

0 

/ 

A 

C 

C 

T 

S 

R 

C 

V 

$0D 

X 
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After  the  Load  call: 


/ 

D 

0 

/ 

A 

C 

C 

T 

S 

R 

C 

V 

$0D 

4 

X 

•  Possible  errors: 


•  Module  directory  full 

•  Memory  full 

•  Errors  that  occur  on  the  Open,  Read,  Close,  and  Link 
system  calls 
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Memory 

OS9  W$mma 
103F  07 

Entry  Conditions: 
D 

Exit 

Y 
D 

Error  Output: 

GO  =  earry  set  on  error 
B      =  error  code  (if  any) 

AdcKHonal  InfDxmaticm: 


Changes  process's  data 
area  size 


=  size  of  the  new  memory  area  (in  bytes); 
0  =  return  current  size  and  upper  bound 

Condilxons: 

-  address  oftfm  mm  memory  etrrn  upper  bound 
=  actual  size  of  the  new  memory  {in  bytes) 


•  The  memory  call  expands  or  contracts  the  process's  data 

memory  area  to  the  specified  size.  Or,  if  you  specify  zero  as 
the  new  size,  the  call  returns  the  current  size  and  upper 
boundaries  of  data  memory. 

•  OS-9  rounds  off  the  size  to  the  next  page  btmn^ry.  In  allo- 
cating additional  meinpry,  OS-9  continues  upward  from  the 
previoos  hi^iest  address.  In  deaUosating  unneeded  mem- 
ory, it  continues  downward  from  that  address, 
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Link  to  a  module  Links  to  a  module; 

0S9  F$NMIiiik  the 
103F  21  module  mto  the  user's 

address  space 


Entry  Conditions: 

A     =  type/ language  byte 

X      =  address  of  the  module  name 


Exit  Conditions: 

A      =  type/language  code 
B      —  module  revision 

X      -  address  of  tlie  last  byte  of  the  module  name  +  1;  any 

trailing  blanks  are  skipped 
Y     =  storage  reqmr&nmt  fbr  ^  module 


Error  Output: 

CC  =  csirry  set  on  error 
B     =  error  code  if  any 


Additional  Information: 

•  Although  this  call  is  similar  to  F$Link,  it  does  not  map 
the  sp^flei  module  inio  the  user's  address  space  but  does 

return  the  memory  requirement  for  the  module.  A  calling 
process  can  use  this  memory  requirement  information  to 
fork  a  program  with  a  maximum  amount  of  space. 
F$NMLink  can  therefore  fork  larger  programs  than  c£ui  be 
forked  ^  l'$Link. 
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Load  a  module 

0S9  F$NMLoad 
103F  22 


Loads  one  or  more 
modules  from  a  file  but 
does  not  map  the 
module  into  the  user's 
address  space 


Entry  Conditions: 

A      =  type/language  byte 
X     =  address  of  the  pathlist 

Esdt  Condifions: 

A  =  type/language  code 

B  =  module  revision 

X  =  address  of  the  last  byte  of  the  pathlist  + 1 

Y  =  storage  requirement  for  the  module 

Error  Output: 

CC    =  carry  set  on  error 
B      =  error  code  if  any 

Additional  Information: 

•  If  you  do  not  provide  a  full  pathlist  for  this  call,  it  attempts 
to  toad  from  a  fite  in  the  current  execution  directory. 

•  Although  this  call  is  similar  to  F$Load,  it  does  not  map 
the  specified  module  into  the  user's  address  space  but  does 
return  the  memory  requirement  for  the  module.  A  calling 
process  can  use  this  memory  requirement  information  to 
fork  a  program  with  a  maximum  amount  of  space. 
F$NMLoad  can  therefore  fork  larger  programs  than  can  be 
forked  by  F$Load. 
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Print  Error 

0S9F$Perr  103F  OF 


Writes  an  error 
message  to  a  specified 
path 


Entry  Conditions: 

B      =  error  code 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  Print  Error  writes  an  error  message  to  the  standard  error 
pilh  for  the  specified  process.  By  d^ult,  OS'9  shows: 

ERROR  #cieGimal  number 

•  The  error  repierMtttg  EWitine  is  vectored.  Using  the  Set  SVC 
system  call,  you  can  replace  it  with  a  more  elaborate 
reporting  module. 
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Parse  Name  Scans  an  input  string 

0S9  WrsNam  103F  M         for  a  vaM  OS-9  name 

Entry  Conditions: 

X     =  address  of  the  pathlist  (See  the  following  example.) 


Exit  Conditions: 

X  =  address  of  the  optional  slash  +  1 

Y  =  address  of  the  last  character  of  the  name  + 1 

A  =  trailing  byte  (Mma^  charaetier) 

B  =  length  of  the  name 


Error  Outputs 

CC    =  carry  set 

B      =  error  code 

Y      =  address  of  the  first  non-delimiter  character  in  the 
string 


Additional  Information: 

•  Parses,  or  scans,  the  input  text  string  for  a  legal  OS-9 
name.  It  terminates  the  name  with  ai^  character  that  is 
not  a  legal  name  character. 

•  Parse  Name  is  useful  for  processii]^  pathlist  arguments 
passed  to  new  processes. 

•  Because  Parse  Name  processes  only  one  name,  you  might 

need  several  calls  to  process  a  pathlist  that  has  more  than 
one  name.  As  you  can  see  from  the  following  example, 
Parse  Name  finishes  with  Register  Y  in  position  for  the 
next  parse. 

•  If  Begistes'  Y  was  at  the  end  of  a  pathlist,  Parse  Name 
returns  a  bad  name  error.  It  then  moves  the  pointer  in  Reg- 
ister Y  past  any  space  characters  so  that  it  can  parse  the 
next  pathlist  in  a  command  line. 
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•  Before  the  Parse  Name  call: 


/ 

D 

0 

/ 

p 

A 

Y 

R 

0 

L 

L 

b 

b 

b 

X 

After  the  Parse  Mame  call: 

/ 

D 

0 

p 

A 

Y 

R 

0 

L 

L 

♦ 

B  = 

2 

X  Y 
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Search  Bits 


Searches  a  specified 
memory  allocation  bit 
map  for  a  free  memory 
Mmk.  of  a  specified 
size 


OS9  F$SchBit  103F  12 


Entry  Conditions: 

D  =  starting  bit  number 

X  =  starting  address  of  the  map 

Y  =  bit  count  (free  bit  block  size) 
U  =  ending  address  of  the  map 

Error  Output: 

CC    =  C  bit  set 

Exit  Conditions: 

D      =  starting  bit  number 

Y  =  bit  count 

Additional  Information: 

•  The  Search  Bit  call  searches  the  specified  allocation  bit 
map  fijr  a  free  block  (cleared  bits)  of  the  required  length. 
The  search  starts  at  the  starting  bit  rmmher.  If  no  block  of 

the  specified  size  exists,  the  call  returns  with  the  carry  set, 
starting  bit  number,  and  size  of  the  largest  block. 
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Send  Sends  a  signal  to  a 

OSS  F$Send  103F  08  specified  process 

Entry  Conditions: 

A      =  destination's  process  ID 
B      =  signal  code 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  ai^) 

Additional  Information: 

•  The  signal  code  is  a  single  byte  value  in  the  range  0 
through  255. 

•  If  the  destination  process  is  sleeping  or  waiting,  OS-9  acti- 
vates the  process  so  that  the  process  can  process  the  signal. 

•  If  a  signal  trap  is  set  up,  F$Send  executes  the  signal  pro- 
cessing routine  (Intercept).  If  none  was  set  up,  the  signal 
tmninates  the  destination  process,  and  the  signal  code 
becomes  the  exit  status.  (See  the  Wait  system  call.)  An 
exception  is  the  wakeup  signal;  that  signal  does  not  cause 
the  signal  intercept  routine  to  be  racecuted. 

•  Signal  codes  are  defined  as  follows: 

0  =  ^stem  terminate 

(cannot  be  intercepted) 

1  =  Wake  up  the  process 

2  =  Keyboard  terminate 

3  =  Keyboard  interrupt 
128-255  =  Usa-  drfined 

•  If  you  try  to  send  a  signal  to  a  process  that  has  a  signal 
pending,  OS-9  cancels  the  current  Send  call,  and  returns 
an  errcBT.  Issue  a  Sleep  call  for  a  few  ticks;  then,  try  again. 

•  The  Sleep  call  saves  CPU  time.  See  the  Intercept,  Wait, 
and  Sleep  system  calls  for  more  information. 
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Temporarily  turns  cxfiF 
the  calling  process 


OS9F$Sleep  103F0A 


Entry  Conditions: 


X     =  One  of  the  following: 


sleep  time  (in  ticks) 

0  (sleep  indefinitely) 

1  (sleep  for  the  remainder  of 
the  current  time  slice) 


Exit  Conditions: 

X      =  sleep  time  minus  the  number  of  ticks  that  the  process 


Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  If  Register  X  contains  0,  OS-9  turns  the  process  off  until  it 
receives  a  signal.  Putting  a  process  to  sleep  is  a  good  way 
to  wait  for  a  signal  or  interrupt  without  wasting  CPU  time. 

•  If  Register  X  contains  1,  OS-9  turns  the  process  off  for  the 
remainder  of  the  process's  current  time  slice.  It  inserts  the 

process  into  the  active  process  queue  immediately.  The  pro- 
cess resumes  execution  when  it  reaches  the  front  of  the 
queue. 

•  If  Register  X  contains  an  integer  in  the  range  2-255,  OS-9 
tuwxs  off  the  process  for  the  specified  number  of  ticks,  n.  It 
inserts  the  process  into  the  active  process  queue  after  n-1 
ticks.  The  process  resumes  execution  when  it  reaches  the 
front  of  the  queue.  If  the  process  receives  a  signal,  it  awak- 
ens before  the  time  has  elapsed. 

•  When  you  select  processes  among  multiple  windows,  you 
might  need  to  set  sleep  for  two  ticks. 


was  asleep 
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Set  Pricirity 


Changiis  priority 
of  a  process 


0S9  F$SPrior  103F  OD  "  process 

Entry  Conditions: 

A     =  process  ID 
B      =  priority 

0  =  lowest 
255  =  highest 

Mwtor  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additionul  hiMxwmUQM 

•  Set  Priority  changes  the  process's  priority  to  the  priority 
specified.  A  process  can  change  another  process's  priority 
only  if  it  has  the  same  user  ID. 
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Set  SWI 


Sets  the  SWI2  and 
SWI3  vectors 


OS9  F$SSWI  103F  OE  "     ""'^'"'^ " 

Entry  Conditions: 

A      =  SWI  type  code 

X     =  address  of  the  user  software  interrupt  routine 

Exit  Conditions: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  Sets  the  interrupt  vectors  for  SWI,  SWI2  and  SWI3 
instruetions. 

•  Each  process  has  its  own  local  vectors.  Each  Set  WWL  mi\ 
getgi  Gxm  type  of  vector  according  to  the  code  number  passed 


1  =  SWI 

2  =  SWI2 

3  =  SWI3 

•  When  OS-9  creates  a  process,  it  initializes  all  three  vectors 
with  the  address  of  the  OS-9  service  call  processor. 

•  Warning:  Microware-supplied  sofitswe  mm  8WI2  to  call 
OS-9.  If  you  reset  this  vector,  these  programs  cannot  work. 
K  you  change  all  three  vectors,  you  cannot  call  OS-9  at  all. 
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Set  Time 


Sets  the  system  time 
and  date 


0S9  F$STime  103F  16  ana  oaie 

Entry  Conditions: 

X      =  relative  address  of  the  time  packet 

ErrcH*  Da%)itt: 

CC    =  C  bit  set 
B      =  error  code 

AMMmal  Infomtaibn: 

•  Set  Time  sets  the  current  system  date  and  time  and  starts 
the  system  real-time  clock.  The  date  and  time  are  passed 
in  a  time  packet  as  fblbws. 

Relative 

Address  Value 


Then,  the  call  makes  a  link  system  call  to  find  the  clock.  If 
the  link  is  successful,  Calls  the  clock  iD^tialization. 
The  clock  initialization: 

1.  Sets  up  hardware  dependent  functions 

2.  Sets  up  the  F$Time  system  call  via  F$SSvc 


0 
1 
2 
3 
4 
5 


year 

month 

day 

hours 

minutes 
seconds 
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Set  User  ID 
Number 

F$SUser  103F  IC 

Entry  Conditioiis: 

Y      =  desired  user  ID  number 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  The  support  module  for  this  call  is  0S9pl. 


Changes  the  current 
user  ID  without 
checking  for  errors  or 
ehtcking  the  ID 
number  of  the  caller 
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Time 


Gets  the  syst^n  date 
and  time 


089  F$Tiine  103F  15 


Entry  Conditions: 


X      =  address  of  the  area  in  which  to  store  the  date  and  time 


Exit  Conditions: 

X      =  date  and  time 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additicmiil  lix^momf^mi 

•  The  Time  call  returns  the  current  system  date  and  time  in 
the  form  of  a  6-byte  packet  (in  binary).  OS-9  copies  the 
packet  to  the  address  passed  in  Register  X. 

•  The  packet  looks  like  this: 

Relative 

Address  Value 


•  Time  is  a  part  of  the  clock  module  and  it  does  not  exist  if 
no  iH-evious  call  to  P$Time  has  been  made. 


packet 


0 
1 
2 
3 
4 
5 


year 
month 
day 
hours 

minutes 
seconds 
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IMink 

OB0F$XJnLuik  103F  02 


IMiuks  Cf emoves 
from  memory)  a 


module  that  is  not 
in  use  and  that  has 
a  link  count  of  0 


Entry  Conditions: 

U     =  address  of  the  module  header 

Error  Output: 

CC  =  eaay  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  Unlink  unlinks  a  module  from  the  eurrent  paroeess's 
address  space,  decreases  its  link  count  by  one  and,  if  the 

link  count  becomes  zero,  returns  the  memory  where  the 
module  was  located  to  the  system  for  use  by  other 
processes. 

•  You  cannot  imlink  system  modules  or  device  driws  that 

are  in  use. 

•  Unlink  operates  in  the  following  order: 

1.  Unlink  tells  OS-9  that  the  calling  process  no  longer 
needs  the  module. 

2.  OS-9  decreases  the  module's  link  count  by  one. 

3.  Wh^  the  resulting  link  count  Is  zero,  OS-9  destroys 
the  module. 

If  any  other  process  is  using  the  module,  the  module's 
link  count  cannot  fall  to  zero.  Therefore,  OS-9  does  not 
destr(^  the  module. 

•  If  you  pass  a  bad  address.  Unlink  cantKJfc  find  a  module  in 
the  module  directory  and  does  not  return  an  error. 
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lUtnk 
A  Module 


module's  link  count, 


module  tram  memmf  If 
the  resulting  link  count 
is  zero 


and  removes  the 


F$UnLoad  103F  ID 


Entry  Conditions: 

A      =  module  type 

X      =  pointer  to  module  name 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Infonnalion: 

•  This  system  call  differs  from  Unlink  in  that  it  uses  a 
pointer  to  the  module  name,  instead  of  the  address  of  the 
module  header. 

•  The  support  module  &r  this  csdl  is  OS9p2. 
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Wait 

OS9F$Wait  103F  04 
Entry  Conditions:  None 

Exit  Conditions: 

A 
B 

Error  Output: 

CC  ==  eany  set  on  error 
B      =  error  code  if  any 

Additional  Information: 


TBmporarily  turns  off  a 
callhig  process 


=  deceased  child  process's  ID 

=  deceased  child  process's  exit  status  code  (if  no  error) 


•  The  Wait  call  turns  off  the  calling  process  until  a  child  pro- 
cess dies,  either  by  executing  an  Exit  system  call,  or  by 
receiving  a  signal.  The  VMt  call  helps  you  save  system 
time. 

•  OS-9  returns  the  child's  process's  ID  and  exit  status  to  the 
parent.  If  the  child  died  because  of  a  signal,  the  exit  status 
byte  (Register  B)  contains  the  signal  code. 

•  If  the  caller  has  several  children,  OS-9  activates  the  caller 
when  the  first  one  dies.  Therefore,  you  need  to  use  one  Wait 
system  call  to  detect  the  termination  of  each  child. 

•  OS-9  immediately  reactivates  the  caller  if  a  child  dies 

before  the  Wait  call.  If  the  caller  has  no  children,  Wait 
returns  an  error.  (See  the  Exit  system  call  for  more 
information.) 

•  If  the  Wait  call  returns  with  the  carry  bit  set,  the  Wait 
function  was  not  successful.  If  the  carry  bit  is  cleared.  Wait 
functioned  normally  and  any  error  that  occurred  in  the 
child  process  is  returned  in  Register  B. 
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I/O  User  System  Calls 


Attach 


Attaches  a  device  to 
the  system  or  verifies 
device  attodhment 


0S9I$Attach  103F  80 


Entry  Conditioits: 

A     =  access  mode 

X     =  address  of  the  deoim  mim  string 

Exit  Conditions: 

%     —  updated  past  devke  mam 

U     =  address  of  the  dmwe  takh  entry 

Error  Output: 

B  =  mror  code  (if  any) 
CC    =  carry  set  on  error 

Additional  Information: 

•  Attach  does  not  reserve  the  device.  It  only  prepares  the 
imnm     later  me  by  poeeii. 

•  OS-9  installs  most  devices  automatical^  on  startup,  fhere- 

fore,  you  need  to  use  Attach  only  when  installing  a  device 
dynamically  or  when  verifying  the  existence  of  a  device.  You 
need  not  use  the  Attach  system  call  to  p^orm  routine  I/O. 

•  The  access  mode  parameter  specifies  the  read  and/or  write 

operations  to  be  allowed.  These  are: 

0  =  Use  any  special  device  capabilities 

1  =  Read  only 

2  =  Write  only 

3  =  Update  (read  and  write) 
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•  Attach  operates  in  this  sequence: 

1.  OS-9  searches  the  system  module  to  see  if  memory  con- 
tains a  device  descriptor  that  has  the  same  name  as  the 
device. 

2a.  OS-9's  next  operation  depends  on  whether  or  not  the 
device  is  already  attached.  If  OS-9  finds  the  descriptor 
and  if  the  device  is  not  already  attached,  OS-9  links  the 
device's  file  manager  and  device  driver.  It  then  places 
the  address  of  the  manager  and  the  driver  in  a  new 
device  table  entry.  OS-9  then  allocates  any  memory 
needed  by  the  device  driver,  and  calls  the  driver's  ini- 
tialization routine  which  initializes  the  haf  d^gure. 

b.  If  0S-#  finds  the  deseiiptw,  m&  if  the  device  is  already 
attached,  OS-9  verifies  the  attachment. 
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Chip:ige  Directory  Changes  the  working 

directory  of  s 
to  a  dfo<eetor3 
by  a  pathlist 


OS*  WChgdir  103F  86  ^^^^^  g^Sd 


Entry  Conditions: 

A      =  access  mode 

X     =  address  of  the  pathlist 


Exit  Conditions: 

X      =  updated  past  pathlist 

Error  Output: 

GC  =  carry  set  on  error 
B      =  error  code  (if  any) 


Additional  Information: 

•  If  the  access  mode  is  read,  write,  or  update,  OS-9  changes 
the  current  data  directory.  If  the  access  mode  is  execute, 
OS-9  chants  the  current  execution  directory. 

•  The  calling  process  must  have  read  access  to  the  directory 
specified  (public  read  if  the  directory  is  not  owned  by  the 

p'ocess). 

•  The  access  modes  are: 

1  -  Read 

2  =  Write 

3  =  Update  (read  and  write) 

4  =  Execute 
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Close  Path  Terminates  an  I/O  path 

0S9I$Close  103F8F 

Entry  Conditions: 

A      =  path  number 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Informaiion; 

•  Close  Path  terminates  the  I/O  path  to  the  file  or  device 
specified  by  path  number.  Until  you  use  another  Open, 
Dup,  or  Create  system  call  for  that  path,  you  can  no  longer 
perform  I/O  to  the  file  or  device. 

•  If  you  close  a  path  to  a  single-user  device,  the  device 
becomes  available  to  other  requesting  processes.  OS-9  de- 
allocates internally  managed  buffers  and  descriptors. 

•  The  Exit  system  call  automatically  closes  all  open  paths. 
Therefore,  you  might  not  need  to  use  the  Close  Path  system 
call  to  close  some  paths. 

•  Do  not  close  a  standard  I/O  patb  tmless  you  want  to  change 
the  file  or  device  to  which  it  corresponds. 

•  Close  Path  performs  an  implied  I$Detach  call.  If  it  causes 
the  device  link  count  to  become  0,  the  device  termination 
routine  is  executed.  See  I$Detaeh  for  additional 
information. 
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Create  File 


Creates  and  opens  a 
disk  file 


OS9  I$Create  103F  83 

Entry  Conditions: 

A      =  access  mode  (write  or  update) 
B      =  file  attributes 

X      =  address  of  the  pathlist;  (See  the  following  example.) 

^Esdt  Omiditions: 

A      =  path  number 

X     =  address  of  the  last  byte  of  the  pathlist  +  1;  skips  any 
trailing  blanks  (See  the  following  example.) 

Error  Output: 

CC  -  mxsj  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  OS-9  parses  the  pathlist  aad  enters  the  new  filename  in  the 
specified  directory.  If  you  &i3  not  specify  a  directory,  OS-9 
enters  the  new  fil^ame  in  the  the  working  directory. 

•  OS-9  gives  the  file  the  attributes  passed  in  Register  B, 
which  has  bits  defined  as  follows: 


•  The  access  mode  parameter  passed  in  Register  A  must  have 
the  write  bit  set  if  any  data  is  to  be  written.  These  access 
codes  are  defined  as  follows:  2  =  write;  3  =  update.  The 
mode  affects  the  file  only  until  the  file  is  closed. 


Bit 


Definition 


0 
1 
2 
3 
4 
5 
6 


Read 
Write 
Execute 
Public  read 
Public  write 
Public  execute 
Sharmble  file 
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•  You  can  reopen  the  file  in  any  access  mode  allowed  by  the 
file  attributes.  (See  the  Open  system  call.) 

•  Files  opened  for  write  can  allovr  fiusta?  data  transEk'  than 
those  opened  for  update  because  update  sometimes  needs  to 

pre-read  sectors. 

•  If  the  execute  bit  (Bit  2)  is  set,  the  file  is  created  in  the 
working  e^cution  directory  instead  of  the  working  data 
directory. 

•  Create  File  causes  an  implicit  I$Attach  call.  If  the  device 
has  not  previously  been  attached,  the  device's  initialization 
routine  is  called. 

•  Later  I/O  calls  use  the  path  niunber  to  identify  the  file, 

until  the  file  is  closed. 

•  OS-9  does  not  allocate  data  storage  for  a  file  at  creation. 
Instead,  it  allocates  the  storage  either  automatically  when 
you  first  issue  a  write  or  explicitly  by  the  Setstat 

subroutine. 

•  If  the  filename  already  exists  in  the  directory,  an  error 
occurs.  If  the  call  specifies  a  non-multiple  file  device  (such 
as  a  printer  or  terminal),  Create  behaves  the  same  as 
Open. 

•  %a  cannot  use  Create  t&  iiake  $$rmix«^,  (Seie  the  Msike 
Directory  system  call  for  instructions  on  how  to  do  make 

directories.) 


•  Before  the  Create  File  call: 


/ 

D 

0 

/ 

w 

0 

R 

K 

$0D 

X 

After  the  Create  File  call: 

/ 

D 

0 

/ 

w 

0 

R 

K 

$0D 

♦ 

X 
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Delete  File  Deletes  a  specified  disk 

OS9  I$Delete  103F  87 

Entry  Conditions: 

X      =  address  of  the  pathlistXSee  the  following  example.) 

Exit  C  onditions: 

X      =  address  of  the  last  byte  of  the  pathlist  +  1;  any  trail- 
ing blanks  are  skipped  (See  the  following  example.) 

Error  Output: 

B  =  error  code  (if  any) 
CC    =  carry  set  on  error 

Additional  Information: 

•  The  Delete  File  call  deletes  the  disk  file  specified  by  the 
pathlist.  The  file  must  have  write  permission  attributes 
IfuMie  write,  if  the  calling  process  is  not  the  tmmstj.  An 
attempt  to  delete  a  device  results  in  an  error.  The  caller 
must  have  non-shareable  write  access  to  the  file  or  an  error 
results. 

Example: 

Before  the  Delete  File  call: 


/ 

D 

0 

/ 

W 

0 

R 

K 

b 

b 

b 

M 

E 

M 

0 

$0D 

X 

After  the  Delete  File  call: 

/ 

D 

0 

/ 

w 

0 

R 

K 

b 

b 

b 

M 

E 

M 

0 

$0D 

X 
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Delete  A  File 

OS9  I$DeIe1^  103F  90 
Entry  Conditions: 

A      =  access  mode 

X      =  address  of  the  pathlist 

Exit  Conditions: 
X 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 


Deletes  a  file  from  the 

current  data  or  current 
execution  directory 


=  address  of  the  last  byte  of  the  pathlist +1;  saay  trailing 
blanks  are  skipped 


•  The  Delete  A  File  call  removes  the  disk  file  specified  by  the 
selected  pathlist.  This  function  is  similar  to  I$Delete  except 
that  it  accepts  an  access  mode  hyte.  If  the  access  mode  is 
execute,  the  call  selects  the  current  execution  directory. 
Otherwise,  it  selects  the  current  data  directory. 

•  If  a  complete  pathlist  is  provided  (the  pathlist  begins  with 
a  slash  (/),  the  access  mode  the  call  ignores  the  access 

mode. 

•  Only  use  this  call  to  delete  a  file.  If  you  attempt  to  use 
I$DeletX  to  delete  a  device,  the  system  returns  an  error. 


8-51 


OS-9  Tkchnical  Refb-ence 


Detach  Device 

0S9  I$DetaGh  103F  81 


Removes  a  device 

from  the  system 
device  table 


Entry  Conditioiis: 

U     =  address  of  the  device  table  entry 

GC  =  raifry  set  cm  caror 
B      =  error  code  (if  any) 

Additional  Information: 

•  The  Detach  Device  call  removes  a  device  from  both  the  sys- 
tem and  the  system  device  table,  assuming  the  device  is  not 
being  used  by  another  process.  You  must  use  this  call  to 
detach  devices  attached  using  the  Attach  system  call. 
Attach  and  Detach  are  both  used  mainly  by  the  10  man- 
ager. SCF  also  uses  Attach  and  Detach  to  set  up  its  second 
device  (echo  device). 

•  This  is  the  sequraice  of  the  operation  of  Detach  Device: 

1.  Detach  Device  calls  the  device  driver's  termination  rou- 
tine. Then,  OS-9  deallocates  any  memory  assigned  to 
the  drivel?. 

2.  OS-9  unlinks  the  associated  device  driver  and  file  man- 
ager modules. 

3.  OS-9  then  removes  the  drivar,  as  long  as  no  other  mod- 
ule is  using  that  driver. 
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Duplicate  Path  Returns  a  synonymous 
OS9  I$Dup  103F  82  P***'  number 

Entry  Conditions: 

A      =  old  path  number  (number  of  path  to  duplicate) 

Exit  Conditions: 

A     =  new  pai^  namfter  (if  no  error) 

Error  Output: 

B     =  error  coAi  (if  error  encoijntered) 
CC    =  carry  set  on  error 

Additional  Information: 

•  The  Bupiiemte  Path  returns  another,  synonymous  patb 
number  for  the  file  or  device  specified  1^  tibe  old  path 

number. 

•  The  shell  uses  the  Duplicate  Path  call  when  it  redirects 
I/O. 

•  System  calls  can  use  either  path  numher  (old  or  new)  to 
operate  on  the  same  file  or  device. 

•  Make  sure  that  no  more  than  one  process  is  performing  I/O 
on  any  one  path  at  the  same  time.  Ccounirrent  I/O  on  the 
same  path  can  cause  unpredictable  results  with  RBF  files. 

•  The  I$Dup  call  always  uses  the  lowest  available  path  num- 
ber. This  lets  you  manipulate  standard  I/O  paths  to  contain 
any  desired  paths. 
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Get  Statui 

0S9I$GetStt  103F8D 

Entry  Conditions: 

A  =  path  number 
B      =  function  code 

Error  Output: 

CC  =  carry  set  on  error 
B     =  error  code  (if  any) 

Additional  Information: 


Returns  the  status  of  a 
file  or  device 


•  The  Status  is  a  wildcard  call.  Use  it  to  handle  device 
parameters  that: 

•  Are  not  the  same  for  all  devices 

•  Are  highly  Imrdware-dependKit 

•  Must  be  viser-changeable 

•  The  ^act  operation  of  the  Get  Status  system  call  depends 
on  the  device  ddver  and  file  manager  associated  with  the 
path.  A  typical  use  is  to  determine  a  terminal's  parameter 

for  such  functions  as  backspace  character  and  echo  on/off. 
The  Get  Status  call  is  commonly  used  with  the  Set  Status 
call. 

•  The  Get  Status  function  codes  that  are  currently  defined 
are  listed  in  the  "Get  Status  System  Calls"  section. 
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Make  Directory     Creates  and  initializes 
OS9  I$MakDir  103F  85  *  directory 

Entry  Conditions: 

B      =  directory  attributes 
X     =  address  of  ifm  pathlist 

Exit  Conditions: 

X      =  address  of  the  last  byte  of  the  pathlist  +1;  Make  Direc- 
tory SMf s  teailiHi  blanks. 

Error  Output: 

B  =  error  code  (if  any) 
CC    =  carry  set  on  error 

Additional  Information: 

•  The  Make  Directory  call  creates  and  initializes  a  directory 
as  specified  by  the  pathlist.  The  directory  contains  only  two 
entries,  one  for  itself  (.)  and  one  for  its  parent  directory  (..) 

•  OS-9  makes  the  calling  process  the  owner  of  the  directory. 

•  Because  the  Make  Directory  call  does  not  open  the  direc- 
tory, it  does  not  return  a  path  number. 

•  The  new  directory  automatically  has  its  directory  bit  set  in 
the  access  permission  attributes.  The  remaining  attributes 
are  specified  by  the  byte  passed  in  Register  B.  The  bits  are 
defined  as  follows: 


Bit  IMiMition 

0  Read 

1  Write 

2  Execute 

3  Public  read 

4  Public  write 

5  Public  execute 

6  Single-U8©r 

7  Don't  cWfi 


8-55 


OS -9  Techniml  Refsrmce 


•  Before  the  Make  Directory  call: 


D 

0 

/ 

N 

E 

W 

D 

I 

R 

$QD 

♦ 

X 

After  the  Make  Directory  call: 

/ 

D 

0 

/ 

N 

E 

W 

D 

I 

R 

$0D 

♦ 

X 
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Open  Path 


OpeAa  a  path  to  an 
existing  file  oi  device 
as  specified  by  the 
pathlist 


0S9  I$Open  103F  84 


Entry  Conditions: 

A     =  access  mode  (D  S  PE  PW  PR  E  W  R) 

X     =  address  of  the  paMist  (See  tile  fidlowing  example.) 

Exit  Conditions: 

A     =  path  number 

X      =  OiMress  of  the  last  byte  of  the  pathlist  +  1 

Error  Output: 

B  =  error  cods  (if  any) 
CC    =  carry  set  tm  &cttx 

Additional  Information: 

•  OS-9  searches  for  the  file  in  one  of  the  following: 

•  The  directory  specified  by  the  pathlist  if  the  pathlist 
begins  with  a  slash. 

•  The  wcprMttf  data  directory  ,  if  the  pathlist  does  not 
begin       a  slash. 

•  The  working  execution  directory,  if  the  pathlist  does  not 
begin  with  a  slash  and  if  the  execution  bit  is  set  in  the 
access  mode. 

•  OS-9  returns  a  path  number  for  later  system  calls  to  use  to 

identify  the  file. 

•  The  access  mode  parameter  lets  you  specify  which  read 
and/or  write  opea'atlons  are  to  be  permitted,  f^'hen  set,  miS^ 
access  mode  bit  enables  one  of  the  following:  Write,  Read, 
Read  and  Write,  Update,  Directory  I/O. 

•  The  access  mode  must  conform  to  the  access  permission 
attributes  associated  with  the  file  or  device.  (See  the  Cre- 
ate system  call.)  Only  the  owner  can  access  a  file  unless 
the  appropriate  public  permission  bits  are  set. 
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•  The  update  mode  might  be  slightly  slower  than  the  others 
because  it  might  require  pre-reading  of  sectors  for  random 
access  of  bytes  within  sectcnrs. 

•  Several  processes  (users)  can  open  files  at  the  same  time. 
Each  device  has  an  attribute  that  specifies  whether  or  not 
it  is  shareable. 

•  Befere  the  Open  Path  call: 


/ 

D 

0 

/ 

A 

C 

c 

T 

S 

p 

A 

Y 

$0D 

X 

After  the  Open 

Path  call: 

/ 

D 

0 

/ 

A 

c 

c 

T 

s 

p 

A 

Y 

$0D 

X 


•  If  the  single-user  bit  is  set,  the  file  is  opened  for  single-user 
access  regardless  of  the  settings  of  the  file's  permission 

bits. 

•  You  must  open  directory  files  for  read  or  write  if  the  direc- 
tory bit  {Bit  7)  is  set  in  the  access  mode. 

•  Open  Path  alwajrs  uses  ihe  lowest  path  number  available 
for  the  process. 
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Read 

OS9I$Read  103F  89 


Reads  n  bytes  from  a 
specified  path 


Entry  Conditions: 

A      -  path  number 

Y  =  number  of  bytes  to  read 

X     =  address  in  which  to  store  the  data 

Exit  Conditions: 

Y  =  number  of  iytes  read 

Error  Output: 

B  =  error  code  (if  any) 
CC    =  carry  set  on  error 

Additional  Information: 

•  The  Read  call  reads  the  specified  number  of  bytes  from  the 
specified  path.  It  returns  the  data  exactly  as  read  from  the 
file/device,  without  additional  processing  or  editing.  The 
path  must  be  opened  in  the  read  or  update  mode. 

•  If  there  is  not  enough  data  in  the  specified  file  to  satisfy 
the  read  request,  the  call  reads  fewer  bytes  than  requested 
but  an  end-of-file  error  is  not  returned.  After  all  data  in  a 
file  is  read,  the  next  I$Bead  call  returns  an  raid-of-file 
eror. 

•  If  the  specified  file  is  open  for  update,  the  record  read  is 

locked  out  on  RBF-type  devices. 

•  The  keyboard  terminate,  keyboard  interrupt,  and  end-of-file 
characters  are  filtered  out  of  the  Entry  Conditions  data  on 
SCF-type  devices  unless  the  corresponding  entries  in  the 
path  descriptor  have  Tjeen  set  to  zero.  Ybu  isigllfc  want  to 
modify  the  device  descriptor  so  that  these  values  are  ini- 
tialized to  zero  ■when  the  path  is  opened. 
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•  The  call  reads  the  number  of  bjrtes  requested  unless  Bead 

encounters  any  of  the  following: 

•  An  end-of-file  character 

•  An  end-of-record  character  (SCF  only) 

•  An  error 
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Read  Line  With      Reads  a  text  line  with 

Editing 

OS9I$ReadLii  103F  SB 

Entry  Conditions: 

A      =  path  number 

X     =  address  at  which  to  store  data 

Y  =  maximum  mimber  of  bytes  to  read 

Exit  Conditions: 

Y  =  mimber  of  bytes  read 

Error  Output: 

B  =  error  code  (if  any) 
CG    =  carry  set  on  error 

Additional  Information: 

•  Read  Line  is  similar  to  Read.  The  difference  is  that  Read 
Line  reads  the  input  file  or  device  until  it  encounters  a  car- 
riage return  character  or  until  it  reaches  the  maximum 
byte  count  specified,  whichever  comes  first.  The  Read  Line 
also  automatically  activates  line  editing  on  character  ori- 
ented devices,  such  as  terminals  and  printers.  The  line 
editing  refers  to  auto  line  feed,  null  padding  at  the  end  of 
the  line,  backspacing,  line  deleting,  and  so  on. 

•  SCF  requires  that  the  last  byte  entered  be  an  end-of-record 
character  (usually  a  carriage  return).  If  more  data  is 
entered  than  the  maximum  specified,  Read  Line  does  not 
accept  it  and  a  PD.OVF  character  (usually  a  bell)  is 
echoed. 

•  After  one  Read  Line  call  reads  all  data  in  a  file,  the  nestt 
Read  Line  call  generates  an  end-of-file  error. 

•  (Pbr  more  information  about  line  editing,  see  "SCF  Line 
Editing  Functions"  in  Chapter  6.) 
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Seek  Repositions  a  file 

0S9  I$Seek  103F  88  pointer 

Entry  Conditions: 

A      =  path  number 

X  =  MS  16  bits  of  the  desired  file  position 
U     =  LS  16  bits  of  the  desired  file  position 

Error  Output: 

CC  =  carry  set  on  error 
B     =  error  code  (if  any) 

Additional  Information: 

•  The  Seek  Call  repositions  the  path's  logical  file  pointer,  the 
32rhlt  address  of  the  next  byte  in  the  file  to  be  read  from  or 

•  You  can  perform  a  seek  to  any  value,  regardless  of  the  file's 

size.  Later  writes  automatically  expand  the  file  to  the 
required  size  (if  possible).  Later  reads,  however,  return  an 
md-«rf-file  condition.  Note  that  a  seek  to  Address  0  is  the 
same  as  a  rewind  operation. 

•  OS-9  usually  ignores  seeks  to  non-random  access  devices, 
and  returns  without  error. 

•  On  RBF  devices,  seeking  to  a  new  disk  sector  causes  the 

internal  disk  buffer  to  be  rewritten  to  disk  if  it  has  been 
modified.  Seek  does  not  change  the  state  of  record  locking. 
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Set  Status  Sets  the  status  of  a  file 

0S9  I$SetStt  103F  8E  device 

Entry  Conditions: 

A  =  path  number 
B      =  function  code 

Other  registers  depend  on  the  function  code. 

Error  Output: 

B  =  error  code  (if  any) 
CC  =  carry  set  on  error 
Other  registers  depend  on  the  function  code. 

Additional  Information: 

•  Set  Status  is  a  wildcard  call.  Use  it  to  handle  device 

parameters  that: 

•  Are  not  the  same  for  all  devices 

•  Are  highly  hardware-dependent 

•  Must  be  user-changeable 

•  The  exact  operation  of  the  Set  Status  system  call  depends 
on  the  device  driver  and  file  manager  associated  with  the 
path.  A  typical  use  is  to  set  a  terminal's  parameters  for 
smch  ftmsimm  as  baskspaee  cfaitraetar  wad  eeho  on/olf.  The 
Set  Status  call  is  commonly  used  with  the  Gret  Status  call. 

•  The  Set  Status  function  codes  that  are  currently  defined 
are  listed  in  the  "Set  Status  System  Calls"  section. 
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Write  Writes  to  a  file  or 

OSS  Write  103F  8A  ^^^^ 

Entry  Conditions: 

A      =  path  number 

X     =  starting  address  ef  dalxi  to  write 

Y  =  number  of  bytes  to  write 

Eadt  Conditions: 

Y  =  number  of  bytes  written 

Error  Output: 

B  =  error  code  (if  any) 
CC    =  carry  set  on  error 

Additional  Information: 

•  The  Write  system  call  writes  to  the  file  or  device  associated 
with  the  path  number  specified. 

•  Before  using  Write,  be  sirre  ^  path  is  opened  or  created 
in  the  Write  or  Update  access  mode.  OS-9  writes  data  to 
the  file  or  device  without  processing  or  editing  the  data. 
OS-9  automatically  expands  the  file  if  you  write  data  past 
the  present  end-of-file. 
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Write  Line 

OS9l$WritLn  103F  8C 


Wi^tes  to  a  file  or 
device  until  it 
encounters  a  carriage 
return 


Entry  Conditions: 

A      =  path  number 

K     =  address  of  the  daia  to  wriU 

Y  =  maximum  number  of  by  tes  to  write 

Exit  Conditions: 

Y  =  number  of  bytes  written 

Error  Output: 

B  =  error  code  (if  any) 
CC    =  carry  set  on  error 

Additional  Information: 

•  Writes  to  the  file  or  device  that  is  associated  with  the  path 
number  specified. 

•  Write  Line  is  similar  to  Write.  The  difference  is  that  Write 

Line  writes  data  until  it  encounters  a  carriage  return  char- 
acter. It  also  activates  line  editing  for  character-oriented 
devices,  such  as  terminals  and  printers.  The  line  editing 
refers  to  auto  line  feed,  null  padding  at  the  end  of  the  line, 
backspacing,  line  dieletiiig,      m  <m. 

•  B       aiing  \\^ite  Line,  be  sure  the  path  is  opened  or  cre- 
ated in  the  write  or  update  access  mode. 

•  (fbr  more  information  about  line  editing,  see  "SCF  Line 
Editing  Functions"  in  Chapter  6.) 
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Privileged  Syst^  Mode  Calls 


Set  an  alarm 

OS9  F$Alann  103F  IE 


Sets  an  alarm  to  ring 
the  bell  at  a  specified 
time 


Entry  Conditions: 

X      =  relative  address  of  time  packet 

Error  Output: 

CC    =  carry  set  on  error 
B      =  appropriate  error  code 

Additional  Information: 

•  When  the  system  reaches  the  speeifled  alarm  time,  it  rings 

the  bell  for  15  seconds. 

•  The  time  packet  is  identical  to  the  packet  used  in  the 
I^Itee  ^11.  See  F$Srime  for  additional  in&rmation  on 
the  &BnmM    the  pieket. 

•  All  alarms  begin  at  the  start  of  a  minute  and  any  seconds 

in  the  packet  are  ignored. 

•  The  system  is  limited  to  one  alarm  at  a  time. 
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AlkmrnMB  64 

OS9F$An64  103F30 


Dynamically  attciiiatlei 
64-byte  blocks  of 
memory 


Entry  Conditions: 

X     =  base  address  of  the  page  table;  0  =  the  page  table  has 
not  been  allocated 

Exit  Conditions: 

A     =  bhck  number 

X     =  base  address  of  the  page  table 

Y     =  address  of  the  block 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  The  Allocate  64  system  call  allocates  the  64-byte  blocks  of 
memory  by  splittinf  pafes  (256-byte  sections)  into  four 
sections. 

•  OS-9  uses  the  first  64  bytes  of  the  base  page  as  a  page 
table.  This  table  contains  the  page  number  (most  signifi- 
cant byte  of  the  address)  of  all  pages  in  the  memory  struc- 
ture. If  Register  X  passes  a  value  of  zero,  the  call  allocates 
a  new  base  page  and  iite  first  i4-l|rte  wmsmf  Mock. 

•  Whenever  a  new  pii^  is  iQieided,  a  Ibquest  System  Meinory 
system  call  CP$SEtiiieED)  meeaim  aut^Elkally. 

•  The  first  byte  of  each  block  contains  the  block  number. 
Routines  that  use  the  Allocate  64  call  should  not  alter  this 
^e. 
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•  The  following  diagram  shows  how  seven  blo(^  mi^t  be 
allocated: 

ix«ao  xii,M.  ^  Memory  Page     Any  Memory  Page 

X 

Block  4 
(64  bytes) 


X 

Block  5 
(64  bytes) 


X 

Block  6 
(64  bytes) 


X 

Block  7 
(§4  bjrtes) 
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(64  lytes) 

X 

Block  1 
(64  bytes) 

X 

Mock  2 
(64  bytes) 

X 

Block  3 
(64  Iq^tes) 

Privileged  ^stem  Mode  Calls  1 8 


Allocate  High        Allocate  system 

RAIW  memory  from  high 

physical  memory 

OS9F$AlHRam  103F  53 


Entry  Conditions: 

B      —  number  of  blocks 


Error  Output: 

CC    =  carry  set  on  error 
B      =  appropriate  error  code 


Additional  Information: 

•  This  call  searches  for  the  desired  number  of  contiguous  free 
RAM  blocks,  starting  its  search  at  the  top  of  memory. 
F$AllHRam  is  similar  to  F$A11RAM  e^ept  F$A11RAM 
begins  its  search  at  the  bottooi  of  memory. 

•  &reen  allocation  routines  use  this  call  to  provide  a  better 
chance  of  finding  the  necessary  memory  for  a  screen. 
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Allocate  Immge 

OS9  F$AllIing  103F  3A 


Allocates  RAM 
blocks  for  process 
DAT  image 


En^  Conditioiis: 

A      =  starting  block  number 

B      =  number  of  blocks 

X     =  process  descriptor  pointer 

Exit  Conditions: 

CC  =  carry  set  on  error 
B     =  error  code  (if  any) 

Additional  Information: 

•  Use  the  Allocate  Image  system  call  to  allocate  a  data  area 
for  a  process.  The  bbcks  that  Allocate  Image  defines  might 
not  be  contiguous. 

•  The  support  module  for  this  system  call  is  0S9pl. 
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Allocate  Process 
Descriptor 

OS9F$AUPrc  103F  4B 

Entry  Conditions:  None 

Exit  Conditions: 

U        process  descriptor  pointer 

Error  Output: 

00   =0  bit  set  on  eiTW 
B     =  appropriate  error  code 

AdditioDal  Information: 

•  The  process  descriptor  table  houses  the  address  of  the 

descriptor.  Initialization  of  the  process  descriptor  consists 
of  clearing  the  first  256  bytes  of  the  descriptor,  setting  up 
the  state  as  a  system  state,  and  marking  as  unallocated  as 
much  of  the  DAT  ima^  as  the  system  allows — ^tjrpically, 
60-64  kilobytes. 

•  The  support  module  for  this  system  call  is  OS9p2.  The  call 
also  branches  to  the  F$SRqMem  call. 


Allocates  and 

initializes  a  512-byte 
process  descriptor 
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AXioQmtB  MAM 

0S9F$A1IEAM  103F  39 


Searches  the 
memory  block  map 
for  the  desired 
number  of 
contiguous  free 
RAM  blocks 


Entry  Conditions: 

B     =  number  of  blocks 

Ejdt  Conditions: 

CC    =  C  bit  set  on  error 
B     =  appropriate  error  code 

Additioaal  Information: 

•  The  support  module  for  this  system  call  is  0S9pl. 
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Allocate  Process 


Entry  Conditions: 

X     =  process  descriptor  pointer 

Error  Output: 

CC    =  Cbit  set 

B      =  appropriate  error  code 

Additional  Information: 

•  If  the  process  does  not  have  a  task  number,  OS-9  allocates 
a  task  number  and  copies  the  DAT  image  into  the  DAT 
hardware. 

«  Use  support  module  for  this  call  is  0S9pl.  Allocate  Process 
Task  number  also  branches  to  F$ResTsk  and  F$SetTsk. 


Task  Number 

0S9F$AUTsk  103F  3F 


OS-9  has  assigned  a 
task  number  to  the 
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Insert  Ptoc^ss 

OS9  F$AProe  103P  2C 


lusigr^  a  -pitmmB  Into 
the  queue  for  e^culion 


Entry  Conditions: 

X     =  address  of  the  process  descriptor 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Infonnation: 

•  The  Insert  Process  system  call  inserts  a  process  into  the 
active  process  qiieue  so  that  OS-9  can  schedule  the  process 

9  OS-9  all  proeesses  in  the  queue  hy  process  age  (the 
count  of  how  many  process  switches  have  occurred  since  the 
process's  last  time  slice).  When  a  process  is  moved  to  the 
active  process  queue,  OS-9  sets  its  age  according  to  its 
priority — the  higher  the  priority,  the  higher  the  age. 

An  exception  is  a  newly  active  process  that  was  deactivated 
while  in  the  system  state.  OS-9  gives  such  a  ppoee^  Wfher 

priority  because  the  process  usually  is  executing  OTtieal 
routines  that  affect  shared  system  resources. 
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Bootstrap  System  Links  either  1^ 

0S9  PtBoot  lOSF  36  r^'^ZSe*  ""^ 

specified  in  the  INIT 
module 


Entry  Conditions:  Nam 


Error  Output: 

CC    =  C  bit  set  on  error 

B      =  appropriate  error  code 


Additional  Information: 

•  When  it  calls  the  linked  module,  Boot  expects  to  receive  a 
pointer  giving  it  the  location  and  size  of  am  area  in  which 
to  search  for  the  new  module. 

•  The  support  module  for  this  call  is  0S9pl.  Bootstrap  Sys- 
tem also  branches  to  the  F$Link  and  F$VModul  system 
calls. 
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Allocates  the 


OS9F$BtMein  103F  36  nearest  bloek)  as 


contiguous  memory 
in  the  system's 
address  space 


Entry  Conditions: 

D      =  byte  count  requested 

Exit  Conditions: 

D      =  byte  count  granted 

U      =  pointer  to  memory  allocated 

Error  Output: 

CC    =  C  bit  set  on  error 
B      =  appropriate  error  code 

Additional  Information: 

•  This  call  is  identical  to  F$SRqMem. 

•  The  Bootstrap  Memory  Bequest  support  module  is  0S9pX. 
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Clear  Specified 
Block 

OS9  F$ClrBIk  103F  50 

Entry  Conditions: 

B      =  number  of  blocks 
U     =  address  of  first  block 

Exit  Conditions:  None 

Additional  Information: 

•  After  Clear  Specified  Block  deallocates  blocks,  the  blocks 
are  free  for  the  process  to  use  for  other  data  or  program 
areas.  If  the  block  address  passed  to  Clear  Specified  Block 
is  invalid  or  if  the  call  att^pts  to  clear  the  stack  area,  it 
returns  E$IBA. 

•  The  support  module  for  the  call  is  OS9p2. 


Marks  blocks  in  the 
process  DAT  image  as 
unallocated 


8-77 


OS -9  Technical  Reference 


DAT  to  Logical 
Address 

OS9  F$DATLog  103F  44 

Ent^  Condidons: 

B     =  DAT  image  offset 
X     =  block  offset 

Exit  Conditions: 

X     =  logical  address 

Error  Output: 

CC    =  C  bit  set  on  error 
B      =  approprials  error  code 

Additional  Information: 

•  Following  is  a  sample  conversion: 


Converts  a  DAT  image 
clock  number  and 
block  offset  to  its 
equivalent  lo^cal 
address 


2000  -  2FFF 


1000  -  IFFF 


0-FFF 


Input:  B  =  2 

X  =  $0329 


Output:  X  =  $2329 


•  The  support  module  for  this  call  is  0S9pl. 
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Dm^mmtm  Image  Deallocates  image 

RAM  Blocks         RAM  blocks 

0S9  F$DeUmg  103F  3B 

Entry  Conditions: 

A      =  number  of  starting  block 

B        =  block 

X     =  process  descriptor  pointer 

Error  Output: 

CO    =  C  bit  set  on  error 
B      =  appropriate  error  code 


Additional  Information: 

•  This  system  call  deallocates  memory  froffi  a  process's 
address  space.  It  frees  the  RAM  for  system  use  and  frees 
the  DAT  image  for  the  process.  Its  main  use  is  to  let  the 
system  clean  up  after  a  process  death. 

•  The  support  module  fear  this  call  is  OS9p2. 
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Deallocate 

Process 

Descriptor 


Mettims  a  process 
descriptor's  memory  to 
a  free  memory  pool 


OS9  F$DelPrc  103F  4C 

Entry  Conditions: 

A      =  process  ID 

Error  Output: 

CC    =  C  bit  set  on  error 
B      =  appropriate  error  code 

Additional  Information: 

•  Use  this  call  to  clear  the  system  scratch  memory  and  stack 

area  associated  with  the  process. 

•  The  support  module  for  this  call  is  OS9p2. 
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Deallocate  RAM 
blocks 

OS9F$DelRAM  103F  51 


Clears  a  block's  RAM 
In  Use  flag  in  the 
system  memory  block 
map 


Entry  Conditions: 

B      =  number  of  blocks 

X     =  starting  block  number 

Exit  Conditions:  None 


Additional  Information: 

•  The  Deallocate  RAM  Blocks  call  assumes  the  blocks  being 
deallocated  are  not  associated  with  any  DAT  image. 

•  The  support  module  for  this  call  is  OS9p2. 
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Releases  Wm  task 


X     =  process  descriptor  poii^ 

Error  Output: 

CC   =  C  bit  set  on  error 
B     =  appropriate  error  code 

Additional  Information: 

•  The  support  module  for  this  call  is  0S9pl. 


the  pam 
pointer 


number  that  the 
process  specified  by 


40 
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Link  Using 
Module  Directory 
Entry 

OS9  F$ELink  103F  4D 

Entry  Conditions: 

B      =  module  type 
X     =  pointer  to  module  directory  ervtey 


Exit  Conditions: 

tJ  =  module  header  address 
Y     =  module  &iify  point 

Error  Output: 

CC    =  C  bit  set  on  error 
B     =  appropriate  error  code 

Additional  Information: 


P&Hbtms  a  link  vts&n§  a 
pointer  to  a  module 
directory  entry 


•  This  call  differs  from  Link  in  that  you  supply  a  pointer  to 
the  module  directory  entry  rather  than  a  pointer  to  a  mod- 
ule name. 

•  The  suppwt  module  for  this  call  is  0S9pl, 
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Find  Module  Retums  a  ]^Qtiit@r  to 

Directory  Entry    *^try  directory 

OS9F$FModul  103F4E 

Entry  Conditions: 

A     =  module  type 

%     s=  pointer  to  the  mme 

Y     =  DAT  image  pointer  (for  name) 

Exit  Conditions: 

A     =  module  type 

B      =  module  revision  number 

X      =  updated  name  string;  (if  Register  A  contains  0  on 
entry) 

U      =  module  directory  entry  pointer 

Error  Output: 

GC    =  C  bit  set  on  error 
B      =  appropriate  error  code 

Additional  Information: 

•  The  Find  Module  Directory  Entry  call  returns  a  pointer  to 
the  module  directory  entry  for  the  first  module  that  lias  a 
name  and  "msMo^vg  1^  specified  mune  and  t^pe.  If 
you  pass  a  module  type  of  z^o,  the  system  call  finds  any 
module. 

•  The  support  module  for  this  call  is  0S9pl. 
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Find  64 


Returns  the  address 
of  a  64-byte  memory 
block 


OS9F$Fmd64  103F2F 


Entry  Conditions: 

A      =  block  number 

X      =  address  of  the  block 

Exit  Conditions: 

Y      =  address  of  the  block 

CC    =  carry  set  if  block  not  allowed  or  not  in  use 

Additional  Information: 

•  OS-9  uses  Find  64  to  find  path  descriptors  when  given 
their  block  number.  The  block  number  can  be  any  positive 
integer. 
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Get  Free  High 
Block 

0S9F$FreeHB  103F3E 

Entry  Conditions: 

B      =  block  count 
Y     =  DAT  image  pointer 

Exit  Conditions: 

A     =  starting  block  number 

Error  Output: 

CX>   =  C  bit  set  on  error 
B      =  appropriate  error  code 

Additibnal  Information: 

•  The  Get  Fret  Mfh  Bliick  ^11  returns  the  block  number  of 
the  beginning  memory  address  of  the  free  blocks. 

•  The  support  module  for  this  system  call  is  0S9pl. 


Searches  the  DAT 
Image  for  the 
highest  set  of 
contiguous  free 
blocks  of  the 
specified  size 
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Get  Free  Low 


OmW$WtmlM  103F3D 


size 


Entry  Conditions: 

B      =  block  count 

Y     =  DAT  image  pointer 

Badt  Conditions: 

A      =  starting  block  number 

Error  Output: 

CC    =  C  bit  set  on  &emt 
B      =  appropriate  error  code 

Additional  Information: 

•  The  Gret  Free  Low  Block  caU  returns  the  btock  number  of 
the  beginning  memory  address  of  the  free  blocks. 

•  The  support  module  for  this  system  call  is  0S9pl. 
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Compact  Module  omp^ti  m 

Directory  module  directory 

OS9  F$GCMDir  103F  52 

Entry  Conditions:  None 

Exit  CondiHons:  None 

Additional  Information: 

•  This  function  is  only  for  internal  OS-9  system  use.  You 
^ould  never  call  it  from  a  program. 
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Get  Process 
Pointer 


Gets  a  pointer  to  a 
process 


F$GProeP  103F37 

Entry  Conditions: 

A     =  process  ID 

Exit  Conditions: 

B      =  pointer  to  process  descriptor  (if  no  error) 

Error  Output: 

CC    =  carry  set  on  error 

B      =  error  code  (If  an  error  occurs  (E$BPrcID)) 

Additional  Information: 

•  The  Get  Process  Pointer  call  translates  a  process  ID  num- 

to  Uie  address  of  its  process  descriptor  in  the  system 
address  space.  Process  descriptors  exist  only  in  the  system 
task  address  space.  Because  of  this,  the  address  returned 
only  refers  to  system  address  space. 

•  The  support  module  for  this  call  is  OS9p2. 
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I/O  Delete 


Deletes  sm.  I/O  in0d:i]2e 
that  is  not  being  used 


OS9  F$IODel  103F  33 


Entry  Conditions: 

X     =  address  of  an  I/O  module 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  The  I/O  Delete  deletes  the  specified  I/O  module  from  the 
system,  if  the  modvile  is  not  in  use.  This  system  call  is 
med  mainly  by  Hie  10  liiANAGER,  mi  mm  1m  dt  limitei 
or  no  use  for  other  applicEtiona. 


1.  Register  X  passes  the  address  of  a  device  descriptor 
module,  device  driver  module,  or  file  manager  module. 

2.  OS-9  searches  the  device  table  for  the  address. 

3.  If  OS-9  finds  the  address,  it  checks  the  module's  use 
count.  If  the  count  is  zero,  the  module  is  not  being 
used;  OS-9  deletes  it.  If  the  count  is  not  zero,  the  mod- 
ule is  being  used;  0S-@  retcns  m^m. 

•  FO  Delete  returns  information  to  the  Unlink  system  call 
after  detennining  M^ietfaer  a  device  is  busy. 


•  This  is      cpte  i&        10  Sdete 
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I/O  Queue 

0S9F$II>%  103F2B 


Ins^s  the  calling 
process  into  another 
process's  I/O  queue, 
attd  puts  liie 
process  to  sleep 


Entry  Conditions: 

A      =  process  number 


Error  Output: 

CC  =  (MBpy  set  on  error 
B      =  error  code  (if  any) 


Additional  Information: 

•  The  I/O  Queue  caU  links  the  calling  froei^  into  the  I/Q 
queue  of  the  specified  process  and  pef^a^  am.  tax^ined 
sleep.  The  10  Manager  and  the  file  Managers  are  primary 

and  extensive  users  of  I/O  Queue. 

•  Routines  associated  with  the  specified  process  send  a  wake- 
up  signal  to  the  calling  process. 
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Adds  a  dcfvice  to  or 
removes  it  from  the 
polling  table 


Entry  Conditions: 

D      =  address  of  the  device  status  register 
X     =0  (to  X0mm  Sl  device)  or  the  address  of  a  packet  (to 
adi  a  Asi^ce) 

•  the  address  at  X  is  the  flip  byte 

•  the  address  at  X  + 1  is  the  mask  byte 

•  the  address  at  X  +  2  is  the  priority  byte 
Y     =  address  of  the  device  IRQ  service  routine 

U     =  address  of  the  service  rmttm's  memory  arm 

Error  Output: 

CC  =  carry  set  on.  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  Set  IRQ  is  used  misinly  by  device  driver  routines.  (See 
^'Ibterrupt  Processing*'  in  CS&apter  2  ^  a  compbte  discus- 
eifia    lige  interrupt  polling  system.) 

•  Ba.<iBt  Definitions: 

The  Flip  Byte.  Determines  whether  the  bits  in  the  device 
status  register  indicate  active  when  set  or  active  when 
cleared.  If  a  bit  in  the  flip  b3d;e  is  set,  it  indicates  that  the 
task  is  active  whenever  the  corresponding  bit  in  the  status 
register  is  etear  (and  vice  v^rsa). 

The  Mask  B^yte.  Selects  one  or  more  bits  within  the  dmice 
status  register  that  are  interrupt  request  flag(s).  One  or 
more  set  bits  identify  which  task  or  device  is  active. 

The  Priority  Byte.  Contains  the  device  priority  number  (0 
=  lowest  priority,  255  =  highest  priority). 
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Load  A  From 
TaskB 


Loads  A  from  0,X  in 
taskB 


F$LDABX  103F  49 

Entry  Conditions: 

B      —  task  number 
X     =  pointer  to  data 

Exit  Conditions: 

A     =  byte  at  OJC  in  task  address  space 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  IbJormalion: 

•  The  value  in  Register  X  is  an  offset  value  from  the  begin- 
ning address  of  the  Task  module.  The  Load  A  From  Task  B 
call  returns  one  byte  from  this  logical  address.  Use  this 
system  call  to  get  one  bj^e  from  the  current  process's  mem- 
ory in  a  system  state  routine. 
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Get  One  Byte  Loads  a  from  [X»  [Y]] 

F$LDAXY  103F  46 

Entry  Conditions: 

X      =  block  offset 

Y     =  DAT  image  pointer 

Exit  Conditions: 

A      =  contents  of  byte  at  DAT  image  (Yj  offset  by  X 

Ei^or  Otitput: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

•  The  Get  One  Byte  system  call  gets  the  contents  of  one  byte 
in  the  specified  memory  block.  The  block  is  specified  by  the 
DAT  image  in  (Y),  offset  by  (X).  The  call  assumes  that  the 
DAP  image  pointer  is  to  the  actual  block  desired,  and  that 
X  is  only  an  offset  within  the  DAT  block.  Ihe  valoe  in  Reg- 
ister X  must  be  less  than  the  size  of  the  DAT  block.  OS-9 
does  not  check  to  see  if  X  is  out  of  range. 
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Get  Two  Bytes         Loads  D  from 
F$LDDDXY  103F  48  ^^'"^^^ 

Entry  Conditions: 

D      =  Offset  to  the  offset  within  the  DAT  image 
X      =  Offset  within  the  DAT  image 
Y      =  DAT  image  pointer 

Exit  Conditions: 

D      =  contents  of  two  hytss  at  [D  +X,Y] 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  Get  Two  Bytes  loads  two  bytes  from  the  address  space 
described  by  the  DAT  image  pointer.  If  the  DAT  image 
pointer  is  to  the  entire  DAT,  then  make  D  +  X  equal  to  the 
process  address  for  data.  If  the  DAT  image  is  not  the  entire 
image  (64K),  then  you  must  adjust  D  +  X  relative  to  the 
beginning  of  the  DAT  image.  Using  D  +  X  lets  you  keep  a 
local  pointer  within  a  block,  and  also  lets  yw  point  to  an 
offset  within  the  DAT  image  that  points  to  a  specified  block 
number. 
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Map  Specific 
Block 

F$MapBlk  103F  4F 


Maps  the  specified 
block(s)  into 
unallocated  blocks  of 
process  space 


Entry  Conditions: 

X      =  starting  block  number 
B     —  number  of  blocks 

Exit  Conditions: 

U      =  address  of  first  block 

Error  Output: 

B  =  error  code  (if  any) 
CC    =  carry  set  on  error 

•  The  system  maps  blocks  from  the  top  down.  It  maps  new 
blocks  into  the  highest  available  addresses  in  the  address 
space.  See  Clear  Specified  Block  for  informatidn  on 
unmapping. 
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Move  Data 

F$Move  103F38 


Moves  data  bytes  tmm. 
one  address  space  to 
another 


Entry  Conditioiis: 

A  =  source  task  number 

B  =  destination  task  number 

X  =  source  pointer 

Y  =  byte  count 

U  =  destination  pointer 

Errfse  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  luformatiom 

•  You  can  use  the  Move  Data  system  call  to  move  data  bytes 
from  one  address  space  to  another,  usually  from  system  to 
user,  or  vice  vesrsa. 

•  The  support  module  &r  this  call  is  0S9pl. 
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Exemties  ilie  next; 
process  in  the  active 
process  queue 


0S9F$NProc  tW  m 


Entry  Conditions:  None 

Exit  Conditions: 

Control  does  not  return  to  caller. 

Additional  Information: 

•  The  Next  Process  system  call  takes  the  next  process  out  of 
the  active  process  queue  and  initiates  its  execution.  If  the 
queue  contains  no  process,  OS-9  waits  for  an  interrupt,  and 

then  checks  the  queue  again. 

•  The  process  calling  Next  Process  must  abready  be  in  one  of 
the  three  process  queues.  If  ft  Is  not,  it  beeomis  untoomn 
to  the  system  even  though  the  process  descriptor  still  easts 
and  can  be  displayed  by  a  PROCS  command. 
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Release  A  Task      Belea«es  a  specified 


Entry  Conditions: 

B      =  task  number 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  The  support  module  for  this  call  0S9pl. 


F$EelTsk  103F43 


DAT  task  number  from 
use  by  a  process, 


hardware  available  for 
use  by  another  task 
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MmMmtWrn  memrms  a  Wm  task 

NlUnbei*  number 

F$BesTsk  103F  42 
Entry  Conditioiis:  none 

Exit  Conditions: 

B     =  task  number  (if  no  error) 

Error  Output: 

CC    =  carry  set  on  error 

B     =  error  code  if  an  error  occurs 

Additional  Information: 

•  The  Reserve  Task  Number  call  finds  a  free  DAT  task  num- 
ber, reserves  it,  and  returns  the  task  number  to  the  caller. 
The  caller  often  then  assigns  the  task  number  to  a  process. 

•  The  support  module  &r  this  call  is  0S9pl. 
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Return  64  Deallocates  a  64-byte 

OS9  F$Ret64  103F  31  memory 

Entry  Conditions: 

A      —  block  number 

X     =  address  of  the  base 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  See  the  Allocate  64  system  call  for  more  information. 
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Set  Process  DAT    Copies  all  or  part  of 


F$SetImg  103F3C 

Entry  Condition: 

A  =  starting  image  block  number 

B  =  block  count 

X  =  process  descriptor  pointer 

U  =  new  image  pointer 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  While  copying  part  or  all  of  the  DAT  image,  this  system 
call  also  sets  an  image  change  flag  in  the  process  descrip- 
tor. This  flag  guarantees  that  as  a  process  returns  from 
the  system  call.  The  call  updates  the  hardware  to  match 
the  new  process  DAT  teaf^. 

•  Hie  support  module  for  this  call  is  0S9pl. 


the  DAT  image  into  a 
process  descriptor 
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Set  Process  Task  Writes  to  the  hardware 
DAT  Registers  registers 

F$SetTsk  103F41 

Entry  Conditions: 

X      =  pointer  to  process  descriptor 

Error  Output: 

CO  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  !biforntji1^xii 

•  This  system  call  sets  the  process  task  hardware  DAT  regis- 
ters, and  clears  the  image  change  flag  in  the  process 
descriptor.  It  also  writes  to  DM"  RAM  the  process's  seg- 
ment address  information. 

•  The  support  module  for  this  call  is  0S9pl. 


8-103 


OS -9  Technical  Reference 


System  Link 

F$SLiiik  103F34 


Adds  a  module  from 
outside  the  current 
adLdn^s  spam  xnio  ^iw 
current  address  space 


Entry  Conditions: 

A      =  module  type 

X      =  module  name  string  pointer 

Y  =  name  string  DAT  image  pointer 

Exit  Conditions: 

A  =  module  type 

B  =  module  revision  (if  no  error) 

X  =  updated  Timm  string  pointer 

Y  =  module  entry  point 
U  =  module  pointer 

Error  Output: 

CC    =  carry  set  on  error 

B      =  error  code  (If  an  error  occurs) 

Additional  Information: 

•  The  I/O  System  uses  the  System  Link  call  to  link  into  the 
current  process's  address  space  those  modules  specified  by  a 
device  name  in  a  user  call.  User  calls  such  as  Create  File 
and  Open  Path  use  this  System  Link. 

•  The  support  module  for  this  call  is  0S9pl. 
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Request  System 
Memory 

Om  FfeRqlto  103F  28 


AUbeates  m  block  of 
memory  of  the 
specified  size  from  the 
top  of  av^dlstlHi  BAM 


Entry  Conditions: 

D     =  byte  count 

Exit  Conditions: 

U  =  starting  address  of  the  memory  area 
D     =  new  memory  size 


Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 


Additional  Information: 

•  The  Request  System  Memory  call  rounds  the  size  request 
to  the  next  page  boundary. 

•  This  call  allocates  memory  only  for  system  address  space. 
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Entry  Conditions: 

U     =  starting  address  of  memory  to  return;  must  point  to  an 

even  page  boundary 
D     =  num.ber  of  bytes  to  return 

Mmar  Output: 

CG  =  carry  iei  am.  erroa: 
B     =  error  code  (if  any) 

Additioinjil  llx^raaatlon: 

•  Bte^ater  U  must  point  to  an  even  page  boundary. 

•  This  call  deallocates  usmm^  for  system  address  space  only. 


Memory 


contiguous  pages 
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Set  SVC 

OSdFfSSvc  103F32 


ikSiiis  or  replaces  a 
system  call 


Entry  Conditions: 


=  address  of  the  system  call 
itiitializfMm  issdls 


Error  Output: 

CC  =  C  bit  set 
B      =  error  code 


Additional  Information: 

•  Set  SVC  adds  or  replaces  a  system  call,  which  you  have 
written,  to  C^<^s  W&c  ftttd  wSf^sem        gptem  call  tables. 

•  Re^ster  Y  passes  the  address  of  a  table,  'which  contains  the 
function  codes  and  offsets,  to  the  corresponding  system  call 
handler  routines.  This  table  has  the  following  format: 

Relative  Use 


$01 
$02 
$03 
$04 
$05 


Function  Oolb 


Offset  From  Byte  3 
To  Function  Handler 


Function  Code 


Offset  From  Byte  6 
To  Function  Handler 


More  Entries 


$80 


■*-  Firist  ^try 


^Second  entry 


•*-  More  entries 


■*-  End-of-table  mark 
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•  If  the  most  significant  bit  of  the  function  code  is  set,  OS-9 

updates  the  system  table. 

If  the  most  significant  bit  of  the  function  code  is  not  set, 
OS-9  updates  the  system  and  user  tables. 

•  The  function  request  codes  are  in  the  range  $29-$34.  10 

calls  are  in  the  range  $80-$90 

•  To  use  a  privileged  system  call,  you  must  be  executing  a 
program  that  reSdes  in  system  map  and  that  executes 
in  the  system  state. 

•  The  system  call  handler  routine  must  process  the  system 
call  and  return  from  the  subroutine  with  an  RTS 
instruction. 

•  The  handler  routine  might  alter  all  CPU  registers  (except 

Register  SP). 

•  Register  U  passes  the  address  of  the  register  stack  to  the 
system  call  hanger  as  liiown  in  the  following  diagram: 


Relative 
Address 

Name 

cc 

$00 
$01 
$01 

R$CC 

R$D 
R$A 

A 

B 

$02 

R$B 

DP 

$03 

RfDP 

X 

$04 

R$X 

Y 

$06 

R$Y 

U 

$08 

R$U 

PC 

$0A 

R$PC 

Codes  $70-$7P  are  reserved  for  user  definition. 
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Store  A  Byte        Bmes  a  at  m  in 
In  A  Task 

F$STABX  103F4A 

Entry  Conditions: 

A      =  t^te  to  store 

B      =  destination  task  number 

X     =  logical  destination  address 

Error  Output: 

CC  =  carry  set  on  mm 
B     =  error  code  (if  any) 

Additional  Information: 

•  This  system  call  is  similar  to  the  assembly  language 
instruction  "STA  0,X".  The  difference  is  that  in  the  system 
call,  X  refers  to  an  address  in  the  given  task's  address 
space,  instead  of  the  current  address  space. 

•  The  support  module  &ir  this  system  call  is  0S9pl. 
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Install  virtual 
interrupt 


Installs  a  virtual 
interrupt  handler 
routine 


0S9F$VIRQ  103F27 

Entry  Conditions: 

D      =  initial  count  value 
X     =  0  to  delete  entry 
1  to  install  entry 
Y     =  address  of  5 -byte  packet 

Error  Output: 

CC    =  carry  set  on  error 
B      =  appropriate  error  code 

Additional  Information: 

•  Install  VIRQ  for  use  with  devices  in  the  Multi-Pak  Expan- 
sion Interface.  This  eall  is  explained  in  detail  in  Chapter  2. 
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Validate  Module 

OitF$VModul  103F2E 

Entry  Conditions: 

D      =  DAT  image  pointer 

X      =  new  module  block  offset 

Exit  Conditions: 


Cheeks  the  ntodiik 
header  parity  and  CRC 
bytes  of  a  module 


U     =  address  of  the  module  directory  entry 

Error  Output: 

CC  =  eatrry  set  m  en-or 
B      =  error  code  (if  any) 

Additional  Information: 

•  If  the  values  of  the  specified  module  are  valid,  OS-9 
searches  the  module  directory  for  a  module  with  the  same 
name.  If  one  exists,  OS-9  keeps  in  memory  the  module  that 
has  the  higher  revision  level.  If  both  modules  have  the  save 
revision  level,  OS-9  retains  the  module  in  memory. 


8-111 


OS -9  Technical  Reference 


Get  Status  System  Calls 

You  use  the  Get  Status  system  calls  with  the  RBF  manager  sub- 
routine GETSTA.  The  OS-9  Level  Two  system  reserves  function 
Caisi  f-If  f  tw  tise  by  Mieroware.  You  can  define  0©<tos  12i-iSS 
their  parameter-passing  conventions  for  your  own  use.  (See 
the  sections  on  device  drivers  in  Chapters  4,  5,  and  6.) 

The  Get  Status  routine  passes  the  register  stack  and  the  speci- 
fied function  code  to  the  device  driver. 

Mlowing  are  the  Gret  Status  functions  and  tiieir  codies. 


SS.QJPT 

(Function  code  $00).  Reads  the  option  section  of  the  path 
descriptor,  and  copies  it  into  the  32-byte  area  pointed  to  by  Reg- 
ister X 

Entry  Conditions: 

A      =  path  number 
B      =  $00 

X     —  address  to  receive  stafm  mmkd 


Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  Use  SS.OPT  to  determine  the  current  settings  for  editing 
functions,  such  as  echo  and  auto  line  feed. 
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SS.RDY 

(Function  code  $01).  Ifests  &r  data  available  on  SCF-supported 

devices 

Entry  Conditions: 

A       -  path  number 
B      =  $01 

Exit  Conditions: 

If  the  device  is  ready: 
CC    =  carry  clear 

B      =  $00 

If  the  device  is  not  ready: 
CG    =  carry  set 
B      =  $F6  {E$SRNDY) 

Error  Output: 

CC    =  carry  set 
B     =  error  code 

SS.SIZ 

(Function  code  $02).  Gets  the  current  file  size  on  a  RBF-sup- 

ported  devices  only 

Entry  Conditions: 

A      =  path  number 
B      =  $02 

Exit  Conditions: 

X  =  most  significant  16  bits  of  the  eUTtmt  file  size 
U     =  least  significant  16  bits  of  the  current  file  size 

Error  Output: 

GC  =  tBXTf  set  on  error 
B     —  error  code  (if  any) 
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(Function  code  $05).  Grets  the  ciirrent  file  position  (RBF-sup- 

ported  devices  only) 

Entry  Conditions: 

A      =  path  number 
B  =$05 

Exit  Coxiditions: 

X  =  most  significant  16  bits  of  the  current  file  position 
U     =  least  significant  16  bits  of  the  current  file  position 

Error  Output: 

CC  5=  maty  set  on  error 
B     =a  m-ror  code  (if  any) 


SS.EOF 

(Function  code  $06).  Tests  for  the  end  of  the  file  (EOF) 

Entry  Conditions: 

A      =  path  number 
B      =  $06 

Exit  Conditions: 

If  there  is  no  EOF: 
CC    =  carry  clear 
B      =  $00 

If  there  is  an  EOF: 
CC  =  ceirry  set 
B      =  $D3  (E$EOF) 

Error  Outpufe 

CC    =  carry  set 
B      =  error  code 
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SS.DevNin 

(Function  Code  $0E).  Retiirns  a  device  name 

Eniary  Conditions: 

A      =  path  number 
B      =  $0E 

X      =  address  of  32 -byte  buffer  for  name 
Eadt  Conditions: 

X      =  address  of  buffer,  name  moved  to  fy^l^ 

SS.DSTAT 

(Function  code  $12).  Retxirns  the  displE^r  status 

Entry  Conditions: 

A      =  path  number 
B      =  $12 

Exit  Conditions: 

A     !=  color  code  of  the  pixel  at  the  cursor  address 

X     =  address  of  the  graphics  dispfai'  mmmry 

Y     =  grapkms  curm'  address;  X  =  MSB,  Y  =  LSB 

AddiMcKtal  InAxFmation; 

•  This  function  is  supported  only  with  the  VDGINT  module 
and  deals  with  VDG-compatible  graphics  screens.  See 
SS.AAGBf  for  information  regarding  Lievel  Two  operation. 
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SS.JOY 

(Fimcticm  code  $13).  Returns  the  joystick  ^^lues 

Entry  Conditions: 

A     =  path  number 
B      =  $13 

X      =  joystick  number 

0  =  (right  joystick) 

1  =  (left  joystick) 

IttiOandiMrais: 

'K     =  fire  button  down 

0  =  none 

1  =  Button  1 

2  =  Button  2 

3  =  Button  1  and  Button  2 
X  =  selected  joystick  x  value  (0-63) 
Y      =  selected  joystick  y  value  (0-63) 

Note:  Under  Level  1,  the  following  values  are  returned  by 
Itts  c  all; 
A     =  fire  button  status 

$FF  =  fire  button  is  on 
$00  =  fire  button  is  off 
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SS.AlfaS 

(Function  code  $1C).  Returns  VDG  alpha  screen  memory 
information 

Entry  Coniitiotts: 

A     =  path  mmber 
B     =  $1C 

Exit  Conditions; 

A      =  caps  lock  status 

$00  =  lower  case 

$FF  =  upper  case 
X     =  memory  address  of  the  buffer 
Y     =  mmnoty  oMmss  ofths  eursor 

AiMltional  Infemation; 

•  SSAlfaS  maps  the  screen  into  the  iiser  address  space.  The 

call  requires  a  full  block  of  memory  for  screen  mapping. 
This  call  is  only  for  use  with  VDG  text  screens  handled  by 
VDGINT. 

•  The  support  module  for  this  call  is  VDGINT. 

•  Warning:  Use  extreme  care  when  pdydng  the  screen,  since 
other  system  variables  reside  in  screen  memory.  Do  not 
change  any  addresses  outside  of  the  screen. 
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SS.Cursr 

(Function  code  $25).  Returns  VDG  alpha  screen  cursor 
infinrmation 

Entry  Conditions: 

A     =  path  number 
B  =$25 

Exit  Conditions: 

A     =  character  code  of  the  character  at  the  current  cursor 
address 

X      =  cursor  X  position  ( column) 
Y      =  cursor  Y  position  (row) 

Additional  Information: 

•  SS.Cursr  returns  the  character  at  the  emrent  cursor  por- 
tion. It  aim  teturns  the  ecUress  c£  #ie  cursor  retaMve 
to  the  current  device's  window  or  screen.  SS.Cursr  works 
only  with  text  screens. 

•  The  support  module  for  this  call  is  VDGINT. 
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SS.ScSiz 

(Function  code  $26).  Returns  the  window  or  screen  size 

Entry  Conditions: 

A     =  path  number 
B      =  $26 

EMI  Cm6momi 

X      =  number  of  columns  on  screen/window 
Y     =  number  of  rows  on  screen/window 

A&litional  Information: 

•  Use  this  call  to  determine  the  size  of  an  output  screen.  The 
values  returned  depend  on  the  device  in  use: 

Ibr  non-CCIO  devices,  the  call  returns  the  values  follow- 
ing the  XON/XOFF  bytes  in  the  device  descriptor. 

Fbr  CCIO  devices,  the  call  returns  the  size  of  the  window 
or  screen  in  use  by  the  specified  device. 

For  window  devices,  the  call  returns  the  size  of  the  cur- 
rent working  area  of  the  window. 

•  The  support  modules  for  this  call  are  VDGINT,  Grfint,  and 
Windlnt. 
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SS.KySns 

(Function  code  $27).  Returns  key  down  status 

Entry  Conditions: 

A     =  path  number 
B      =  $27 

Exit  Conditions: 

A     =  k^board  scan  infis'mfttion 
Additional  Information: 

•  Accumulator  A  returns  with  a  bit  pattern  reptesenting 

eight  keys.  With  each  keyboard  scan,  0S9  updates  this  bit 
pattern.  A  set  bit  (1)  indicates  that  a  key  was  pressed  since 
the  last  scan.  A  clear  bit  (0)  indicates  that  a  key  was  not 
pressed.  Definitions  for  the  bits  are  as  follows: 


The  bits  can  be  masked  with  the  following  equates: 


SHIFTBIT 

equ 

%00000001 

CNTRLBIT 

equ 

%00000010 

AUERBIT 

equ 

%00000100 

UPBFT 

equ 

%00G01000 

DOWNBIT 

equ 

%00010000 

LEFTBIT 

equ 

%00100000 

RIGHTBIT 

equ 

%01000000 

SPACEBIT 

equ 

%10000000 

•  The  support  module  for  this  call  is  CC3I0. 


Bit 

0 

1 

2 

3 

4 

5 

6 

7 


Key 


rCTRLl  or  I  CLEAR  | 

[alt]  or  [@] 
r^l  (up  arrow) 
rri  (down  arrow) 
Q  (left  arrow) 
F^l  (right  arrow) 
Space  Bar 
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SS.ComSt 

(Function  code  $28).  Return  serial  port  configuration 

information 

Entry  Conditions: 

A      =  path  number 
B      =  $28 

Exit  Conditions: 

Y      =  high  byte:  parity 

low  byte:  baud  rate 

(See  the  ^itatat  call  i§.domSt  fin'  i^aluies) 

Error  Ontpail^ 

GC  =  carry  set  m  mt&t 
B     =  0Tor  mdk  (if  any) 

Additional  Infonnation: 

•  The  SCF  manager  uses  this  call  when  performing  an 
SS.Opt  Getstat  on  an  SCF-type  device.  User  calls  to 
SS.ComSt  do  not  update  the  path  descriptor.  Use  the 
SS.OPT  Getstat  call  for  most  applications,  because  it  auto- 
matically updates  the  path  descriptor. 
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SS.MnSel 

(Function  code  $87).  Requests  that  the  high-level  menu  handler 
take  control  of  menu  selection 

Entry  Conditions: 

A     =  path  number 
B  =$87 

Exit  Conditions: 

A      =  menu  ID  (if  valid  selection) 

0  (if  invalid  selection) 
B     =  item  number  of  merm  (if  valid  selection) 

Error  Output: 

CG    =  carry  set  on  error 

B      =  error  code  (if  invalid  selection) 

Additional  Information: 

•  After  detecting  a  valid  mouse  dick  (when  the  mouse  is 
pointing  to  a  control  area  on  a  window),  a  process  needs  to 
call  SS.MnSel.  This  call  tells  the  enhanced  window  inter- 
face to  handle  any  menu  selection  being  made.  If  accumula- 
tor A  returns  with  0,  ttien  no  selection  has  been  made.  The 
calling  process  needs  to  test  and  handle  other  returned 
values. 

•  A  condition  where  Register  A  returns  a  valid  menu  ID 
number  and  Register  B  returns  0  signals  the  selection  of  a 
menu  with  no  items.  The  application  can  now  take  over  and 
do  a  special  graphics  pull  i^wn  df  its  ofwn.  The  mmi  title 
remains  highlighted  until  the  application  calls  the 
SS.UMBar  SetStat  to  update  the  menu  bar. 

•  The  support  module  for  this  call  is  Windlnt. 
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SS.Mouse 


(Funetion  code  $89).  Gets  mouse  status 

Entry  Conditions: 

A      =  path  number 
B      =  $89 

X     =  data  stot^e  area  address 

Y      =  mouse  port  select: 

0  =  automatic  selection 

1  =  right  side 

2  =  left  side 

Exit  Conditions: 

X     =  data  storage  area  address 

Error  Output: 

CC  =  carry  set  on  error 
B     =  errQr  e&de  (if  any) 
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Additional  Infiormation: 


•  SS.Mouse  returns  information  on  the  current  mouse  and  its 
fire  button.  The  following  list  defines  the  32-byte  data 
packet  that  SS-Mouse  creates; 


Pt.Valid 

rmb  1 

Is  rettiraed  info  validf  (0  =  no, 

1  =  yes) 

Pt.Actv 

rmb  1 

Active  side  (0  =  off,  1  =  right,  2  = 
left) 

PtToTm 

rmb  1 

Timeout  initial  value 

rmb  1 

Time  until  timeout 

rmb  2 

RESERVED 

Pt.TSSt 

rmb  2 

Time  since  counter  start 

Pt.CBSA 

rmb  1 

Current  button  state       (Button  A) 

Pt.CBSB 

rmb  1 

Currejit  button  state       (Button  B) 

Pt.CC!tA 

rmb  1 

Click  count                  (Button  A) 

Pt.CCtB 

rmb  1 

Click  count                    (Button  B) 

Pt.TTSA 

rmb  1 

Time  this  state  counter    (Button  A) 

Pt.TTSB 

rmb  1 

Time  this  state  eouttfeer    (Button  B) 

Pt.TLSA 

rmb  1 

Time  last  state  counter    (Button  A) 

Pt.TLSB 

rmb  1 

Time  last  state  counter    (Button  B) 

rmb  2 

RESERVED 

Pt.BDX 

rmb  2 

Button  down  frozen  Actual  X 

Pt.BDY 

rmb  2 

Button  down  frazen  Actual  Y 

Pt.Stat 

rmb  1 

Window  pointer  type  location 

Pt.Res 

rmb  1 

Resolution  (0-640  by  0  =  10/1  =  1) 

Pt.AcX 

rmb  2 

Actual  X  value 

Pt.AcY 

rmb  2 

Actual  Y  value 

Pt.WRX 

rmb  i 

Window  relative  X 

Pt.WRY 

rmb  2 

Window  relative  Y 

Pt.Siz 

equ  . 

Packet  size  32  bytes 

SPt.SRX 

rmb  2 

System  use,  screen  relative  X 

SPt.SRY 

rmb  2 

System  use,  screen  relative  Y 
Size  of  packet  to  system  use 

SPt.Siz 

equ . 

•  Button  Information: 


Pt.'^lilid.  The  valid  byte  gives  the  caller  an  in&cation  of 
whether  the  information  contained  in  the  returned  packet 
is  accurate.  The  information  returned  by  this  call  is  only 
valid  if  the  process  is  running  on  the  current  interactive 
window.  If  the  process  is  on  a  non-interactive  window,  the 
l^e  is  zero  and  the  process  can  ignore  the  information 
returned. 
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Pt.Actv.  This  byte  shows  which  port  is  selected  for  use  by 
aU  mmm  ^3Xi^A^3m*  The  d^tsit  ^^Sm  is  Bight  (1).  liba  can 
change  this  vahie  with  the  SS.6IP  Setstat  call. 

Pt-TbTm.  This  is  the  value  used  by  Pt.TTTo. 

Pt.TTTo.  This  is  the  count  down  value  (as  of  the  instant 
the  Getstat  call  is  made).  This  value  starts  at  the  value 
contained  in  the  Pt.ToTm  and  counts  down  to  zero  at  a  rate 
of  60  coimts  per  second.  The  system  maintains  all  counters 
until  this  value  reaches  0,  at  which  point  it  sets  all 
counters  and  states  to  0.  The  mouse  scan  routine  changes 
into  a  quiet  mode  which  requires  less  overhead  than  when 
the  mouse  is  active.  The  timeout  begins  when  both  buttons 
are  in  the  up  (open)  state.  The  timer  is  reinitialized  to  the 
vahie  in  Pt-ToTm  when  either  button  goes  down  (closed). 

Pt.TSSt.  This  counter  is  constantly  increasing,  beginning 

when  either  button  is  pressed  while  the  mouse  is  in  the 
quiet  state.  All  counts  are  a  number  of  ticks  (60  per  sec- 
ond). The  timer  counts  to  $FFFF,  then  stsgrs  at  that  value 
if  additional  ticks  occur. 

Pt.CBSA,  These  flag  b;ytes  indicate  the  state  of  the  button 
Pt.CBSB.  at  the  last  system  clock  tick.  A  value  of  0  indi- 
cates that  the  button  is  up  (open).  A  value  other  than  zero 
indicates  that  the  button  is  down  (closed).  Button  A  is 
available  on  all  Tandy  joysticks  and  mice.  Button  B  is  only 
available  for  products  that  have  two  buttons. 

The  system  scans  the  mouse  buttons  each  time  it  scans  the 
keyboard. 

Pt.CCtA.  This  is  the  number  of  clicks  that  have  occurred 
Pt.CCtB.  since  the  mouse  went  into  an  active  state.  A 
click  is  defined  as  pressing  (closing)  the  button,  then  releas- 
ing (opening)  the  button.  The  system  coiints  the  clicks  as 
the  button  is  released. 

Pt.TTSA.  This  counter  is  the  nmnber  of  ticks  that  have 
Pt.TTSB.  occurred  during  the  current  state,  as  defined  by 

Pt.CBSx.  This  counter  starts  at  one  (counts  the  tick  when 
the  state  changes)  and  increases  by  one  for  each  tick  that 
occurs  while  tl^  button  remains  in  the  same  state  (open  or 
closed). 
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Pt.TLSA.  This  counter  is  the  niimber  of  ticks  that  have 
PtSt^B.  occurred  duriTig  the  time  that  a  button  is  in  a 
state  (^posite  of  the  current  state.  Using  this  count  and 
the  TTSA/TTSB  count,  you  can  determine  how  a  button 
was  in  the  previous  state,  even  if  the  system  returns  the 
packet  after  the  state  has  changed.  Use  these  counters, 
along  with  the  state  and  click  count  values,  to  define  any 
type  of  diek,  d^a|^,  m  hdd  convention  you  want. 

Reserved.  Two  packet  bytes  are  reserved  for  future  expan- 
sion of  the  returned  data. 

•  Position  Information: 

Pt.BDX.  These  values  are  copies  of  the  Pt.AcX  and  Pt.AcY 
Pt.BDY.  values  when  either  of  the  buttons  change  from  an 

open  state  to  a  closed  state. 

PtStsit,.  This  byte  contains  information  about  the  area  of 
the  screen  on  which  the  mouse  is  positioned.  Pt. Valid  must 

be  a  value  other  than  0  for  this  information  to  be  accurate. 
If  Pt. Valid  is  0,  this  value  is  also  0  and  not  accurate.  Three 
types  a£  areas  are  cuis^oi^  deCbied: 

0  =  content  region  or  current  working  area  of  the 

window 

1  =  control  region  (for  use  by  Multi-View) 

2  =  off  window,  or  on  an  area  of  the  acremx  that  is  not 

part  of  the  window 

Pt.Res.  This  value  is  the  current  resolution  for  the  mouse, 
•nh©  Wil^  aswit  S3m^  return  coordinates  in  the  range  of 
0-639  ^  K  axis  and  0-191  for  the  Y  axis.  If  the  system 
is  BO  configured,  you  can  use  the  high-resolution  mouse 
adapter  which  provides  a  1  to  1  ratio  with  these  values  plus 
1.  If  the  adapter  is  not  in  use,  the  resolution  is  a  ratio  of  1 
to  10  OQ  E  ai^  and  l%Bm  Mie  Y  axis.  The  keyboard 
mouse  proviiis  ft  resolution  of  1  to  1.  The  values  in  Pt.Res 
are: 

0  =  low  res  (x:10,  y:3) 

1  =  high  res  (x,y:l) 

Pt.AcX.  The  values  read  from  the  mouse  returned  in  the 
Pt,AcY.  resolution  as  described  under  Pt.Res. 
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Pt,WRX.  The  values  read  from  the  mouse  minus  the 
Pt-WKy.  starting  coordinates  of  the  current  window's 
working  area.  These  values  return  the  coordinates  in  num- 
bers relative  to  the  type  of  screen.  For  example,  the  X  axis 
is  in  the  range  0-639  for  high-resolution  screens  and  0-319 
for  low  resolution  screens.  Yaa.  can  divide  the  window  rela^- 
tive  values  by  8  t©  dbtain  absolute  ehiracter  positions. 
These  values  are  most  helpful  when  working  in  non-scaled 
modes. 

•  The  support  modules  for  this  call  are  CC3I0,  Grfint,  and 
Windlnt. 


SS.Palet 

(Functioii  code  $91).  Gets  palette  intonation 

Entry  Conditions: 

A      =  path  number 
B      =  $91 

X  =  pointer  to  the  16-byte  paktte  infi)rmation  buffer 
Exit  Conditions: 

X  =  pointer  to  the  16-byis  pc^lette  infbrmatum  buffer 
Additional  Infoirmation: 

•  SS,I^et  reads  the  contents  of  the  16  screen  palette  regis- 
ters, and  stees  Iten  in  a  16-byte  buffer.  When  you  make 
the  call,  be  sure  the  X  register  points  to  the  desined  buffer 
location.  The  pointer  is  retained  on  exit.  The  palette  values 
retiirned  are  specific  to  the  screen  on  which  the  call  is 
made. 

•  The  support  modules  for  this  call  are  VDGINT,  Grflntj  and 
Windlnt. 
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SS.ScTyp 

(Function  code  $93).  Returns  the  type  of  a  screen  to  a  calling 

A     =  path 
B  ^^$93 

Exit  CoiidiiipD^; 

A      =  screen  type  code 

1  =  40  X  24  text  screen 

2  =  80  X  24  text  screen 

3  =  not  used 

4  =  fsdt  used 

5  =  640  X  192,  2-color  graphics  screen 

6  =  320  X  192,  4-color  graphics  screen 

7  =  640  X  192,  4-color  graphics  screen 

8  =  320  X  192,  16-color  graphics  screen 

Additional  Information: 

•  Support  modules  for  this  system  call  are  Grfint  and 
Windlnt. 
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SS.FBRgs 

(Function  code  $96).  Returns  the  finreground,  background  and 

border  palette  registers  for  a  window. 

Entry  Conditions: 

A      —  path  number 
B      =  $96 

Exit  Conditions: 

A      =  foreground  palette  register  number 

B      =  background  palette  register  number  (if  carry  clear) 

X     =  least  significant  byte  of  border  palette  register  number 

Error  Output: 

B      =  error  code  if  any 
GC    =  carry  set  on  error 

Additional  Informalion: 

•  Support  modules  for  SS.FBRgs  are  Grflnt  and  WiiMilnt. 

SS.DFPal 

(Function  code  $97).  Returns  the  default  palette  register 
settings. 

Entry  CondUions: 

A     =  path  number 
B      =  $97 

X      =  pointer  to  16-byte  data  space 
Exit  Conditions: 

X      =  default  palette  data  moved  to  user  space 

Error  Output: 

B      =  error  code,  if  any 
GC    =  carry  set  cm  error 
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Additional  Information: 

•  Ym  can  use  SS.DFPal  to  find  the  values  of  the  default  pal- 
ette r^stors  that  are  used  when  a  new  screen  is  allocated 
by  GrfTht  or  Windlnt.  Tlie  corresponding  SetStat  can  alter 
the  default  registers.  This  GetStat/SetStat  pair  is  for  sys- 
tem configuration  utilities  and  should  not  be  used  by  gen- 
eral applications. 

Set  Status  System  Calls 

Use  the  Set  Status  system  calls  with  the  RBF  manager  subrou- 
tine SETSTA.  The  OS-9  Level  Two  system  reserves  function 
Codes  7-127  for  use  by  Microware.  You  can  define  Codes  200-255 
and  their  parameter-passing  conventions  for  your  own  use.  (See 
the  sections  on  d^iiee  drivers  in  Chapt^s  4,  5,  and  6.) 

fbllomng  are      Set  Slaitw  fttneticms  mi  Htmr  codes. 
SS.OPT 

(Function  code  $00).  '\A^ites  the  option  section  of  the  path 

descriptor 

Entry  Conditions: 

A      =  path  number 
B      =  $00 

X     =  mMrms  of  the  status  packet 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  SS.OPT  writes  the  option  section  of  the  path  descriptor 

from  the  32-byte  status  packet  pointed  to  by  Register  X. 
Use  this  system  call  to  set  the  device  operating  parameters, 
such  as  echo  and  line  feed. 
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SS.SIZ 

(Function  code  $02).  Changes  the  size  of  a  file  for  RBF-type 

devices 

Entry  Conditions: 

A  =  path  number 

B  =  $02 

X  =  most  significant  16  bits  of  the  desired  file  size 

U  =  least  significant  16  bits  of  tte  ^W?*8iS  jife  sige 

Error  Output: 

CC  =  carry  set  on  enror 
B     =  error  code  (if  any) 


SS.RESET 

(Function  code  $03).  Restores  the  disk  drive  head  to  Track  0  in 
preparation  itf  formatting  and  error;  recovery  (use  only  with 
RBF-t5T)e  devices) 

Entry  Conditions: 

A      =  path  number 
B      =  $03 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 
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(Function  code  $04).  Ibrmats  (writes)  a  track  on  a  disk  (RBF- 

type  devices  only) 

Entry  Conditions: 

A      =  path  number 
B      =  $04 

U     =  track  number  (least  significant  8  hits) 
X     =  oMfess  of  the  trmh  m^jkr 
Y      =  side/density 

Bit  BO  =  side 

0  =  Side  0 

1  =  Side  1 
Bit  Bl  =  density 

0  =  single 

1  =  double 

Error  Output: 

CXI  =  carry  set  on  error 
B     =  error  code  (if  any) 

Additional  Informalion: 

•  Fbr  hard  disks  or  floppy  disks  that  have  a  "format  entire 
diskette  command,"  SS^WTRK  formats  the  entire  disk  only 
■v^Bte  f he        /mrnlm'  Is  zera. 
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SS.SQD 

(Function  code  $0C).  Starts  the  shutdown  procedure  for  a  hard 
disk  that  has  sequence-down  requirements  prior  to  removal  of 
power.  (Use  only  with  RBF-type  devices.) 

Entry  Conditions: 

A      =  path  number 
B      =  $0C 

Exit  Conditions:  None 
SS.%Sns 

(Function  code  $27).  Turns  the  key  sense  function  on  and  off 
Entry  Conditions: 

A      =  path  number 

B      =  $27 

X      =  key  sense  switch  value 

0  =  normal  c^^ation 

1  =  key  sense  c^^ation 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  When  SS.KySns  switches  the  keyboard  to  key  sense  mode, 

the  CC3I0  module  suspends  transmission  of  keyboard  char- 
acters to  the  SCF  manager  and  the  user.  While  the  com- 
puter is  in  key  sense  mode,  the  only  way  to  detect  press 
is  with  SS.KySns. 

•  The  support  module  for  this  call  is  CC3I0. 
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SS.ComSt 


(Function  code  $28).  Used  by  the  SCF  manager  to  configure  a 
serial  port 

Entry  Conditions: 

A     =  path  number 
B      =  $28 

Y      =  high  byte:  parity 
low  byte:  baud  rate 

Error  Output: 

CO  =!  eaxTj  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

Baud  Configuration.  The  high  order  byte  of  Y  determines  the 
tfflcttd  rate,  &  'vrajd  length,  and  numbo:  of  stop  bits.  The  byte  is 
caufigured  as :  ~' 


PD.BAU 


7  I  6  I  5 


3  I  2  I  1  I  0 


Baud  rate 
Reserved 
Word  length 
Sj!Opbits 


Stop  bits: 

0  =  1 

1  =  2 

Word  Jeogth: 
00  =  8  bit 


01  = 

7  bit 

Baud  rate: 

0000 

=  110 

0001 

=  300 

0010 

=  600 

0011 

^  1200 

0100 

=  2400 

0101 

=  4800 

0110 

=  9600 

0111 

=  19200 

3,^^. 

=5  ttt^^ 
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•  Parity  Configuration.  The  low  order  l?yte  of  Y  determines 
parity.  The  byte  is  configured  as  ^lows: 


PD.BAU  I  7  I  6  I  S  I  4  [  3  I  2  I  1  I  0 


Special  use 
 Parity 


Parity: 

xxO 

=  none 

001 

=  odd  (ACIAPAK  and  MODPAK  only) 

Oil 

=  even  (ACIAPAK  and  MODPAK  only) 

101 

=  transmit:  mark 

receive:  ignore 

111 

=  transmit:  space 

receive:  ignore 

•  The  SCF  manager  uses  SS.ComSt  to  inform  a  driver  that 
serial  port  configuration  information  has  been  changed  in 
the  path  descriptor.  After  caBing  ii.Ooia§t,  a  meat  mm^Hae 
must  call  the  SS.OPT  SetStat  to  eowectly  update  the  path 

descriptor. 

•  This  call  is  for  the  use  of  the  SCF  manager.  Use  SS.OPT 
for  changing  baud,  stop  bit,  and  parity  values. 

SS.Close 

(Function  code  $2A).  Informs  a  device  driver  that  a  path  is 

closed. 

Additional  Information: 

This  call  is  used  internally  by  OS-9's  SCF  file  manager  and  is 
not  available  for  user  programs.  It  can  be  used  only  l^y  device 
drivers  and  file  managers. 
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SS.AAGBf 

(Function  code  $80).  Reserves  an  additional  graphics  buffer 

Entry  Conditions: 

A     =  path  number 
B  =$80 

Exit  Conditians: 

X     =  buffer  address 

T     =  bi^Her  number  ( 1  -2) 

Mwmr  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  SSAAGBf  allocates  an  additional  8K  graphics  buffer.  The 
first  buffer  (Buffer  0)  must  be  allocated  by  using  the  DIS- 
PLAY" GRAPHICS  command.  Tb  use  the  DISPLAY  GRAPH- 
ICS cdittinand,  aeiid  control  code  f  OP  to  the  slasdard 
terminal  driver.  SS.AAGBf  can  allocate  up  to  two  addi- 
tional buffers  (Buffers  1  and  2),  one  at  a  time. 

•  After  calling  SSAAGBf,  Register  X  contains  the  address  of 
the  new  bti^r.  Register  Y  contains  the  buffer  numb^. 

•  To  deallocate  all  graphics  buffers,  use  the  END  GRAPHICS 

control  code. 

•  When  SS.AAGBf  allocates  a  bu£^,  it  also  maps  the  buffer 
into  the  application's  address  space.  Each  buffer  uses  8K  <£ 

the  available  memory  in  the  application's  address  space. 
Also,  if  SS.DStat  is  called.  Buffer  0  is  also  mapped  into  the 
application's  address  space.  Allocation  of  all  three  lm£^s 
reduces  the  application's  free  memory  by  24K. 

•  The  support  modijle  for  this  call  is  VDGINT. 
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SS.SLGBf 

(Funetsicili  code  $81).  Selects  a  graphics  bu£fer 

Entry  Conditions: 

A     =  path  number 
B      =  $81 

X      =  $00        select  buffer  for  use 

$01-$FF  sdect  buffer  for  use  and  display 

Y  =  buffer  number  (0-2) 

EMt  CondMcms: 

X     =  umhanged  from  entry 

Y  =  unchanged  frwn  entry 

En^oat  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  Use  DISPLAY  GRAPHICS  to  allocate  the  first  graphics 
buffer.  Use  SS.AAGBf  to  allocate  the  second  aai  third 
graphics  buffers. 

•  Save  each  return  address  when  writing  directly  to  a  screen. 
It  is  not  aece^ary  to  mm  i^ttiru  fSldresses  when  using 
(grating  ^stem  gra^tic^  mmmsjoiis. 

•  SS.SLGBf  does  not  update  hardware  information  until  the 
next  vertical  retrace  (60Hz  rate).  Programs  that  use 
SS.AAGBf  to  change  current  draw  buffers  need  to  wait  long 
enough  to  ensure  that  OS-9  has  moved  the  current  buffer  to 
the  scre^. 

•  Hie  screen  shows  the  boflfer  only  if  the  buffer  is  selected  as 

the  interactive  device.  If  the  device  does  not  possess  the 
keyboard,  OS-9  stores  the  information  until  the  device  is 
selected  as  the  interactive  device.  When  the  device  is 
selected  as  the  interactive  device,  the  display  shows  the 
selected  device^  sareen. 

•  The  support  module  for  this  call  is  VDGINT. 
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ssMpam 

(Function  code  $84).  Maps  the  Get/Put  buffer  into  a  usm- 

address  space 

Entry  Conditions: 

A      =  path  number 
B  =$84 

X     =  high  byte:  buffer  group  number 
tma  l^e:  bufjer  nummsr 

Y  =  action  to  take 

1  —  map  buffer 
0  =  unmap  buffer 

Exit  Conditians: 

X      =  address  of  the  mapped  buffer 

Y  =  number  of  bytes  in  buffer 

Error  Output: 

CC  =  carry  set  on  error 
B     =  emr  code  iif  my) 

Addiiiiiiiiil  Boiieisaliioii: 

•  The  support  modules     this  call  are  j^rtttint  md  Wiailat. 

•  SS.MpGPB  maps  a  Get/ftit  buffer  into  the  user  aMress 
space.  You  can  then  save  the  buffer  to  disk  or  directly  mod- 
ify the  pixel  data  contained  in  the  buffer.  Use  extreme  care 
when  modifying  the  buffer  so  that  you  do  not  write  outside 
of  the  buffer  data  area. 
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SS.WnSet 

(Fuiu^iiBi  eoiie  $86),  Set  up  a  high  level  window  handler 

Entry  Conditions: 

A  =  path  number 

B  =  $86 

X  =  window  data  pointer  (if  Y  =  WT.FSWin  or  WT. Win) 

Y  =  window  type  code 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  coA  (if  any) 

Additiouid  Infonnattaffi 

•  The  C  language  data  structures  for  windowing  are  defined 
in  the  wind.h  file  in  the  DEFS  directory  of  the  system  disk. 

•  The  support  module  for  this  call  is  Windlnt. 


SS.SBar 

(Function  code  $88).  Puts  a  scroll  block  at  a  specified  position 

Entry  Conditions: 

A  =  path  number 

B  =  $88 

X  =  horizontal  position  of  scroll  block 

Y  =  vertical  position  of  scroll  block 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  WT.FSWin-tjT)e  windows  have  areas  at  the  bottom  and 
right  sides  to  indicate  their  relative  positions  within  a 
larger  area.  TheM  areas  are  called  scroll  bars.  SS.SBar 

gives  an  application  the  ability  to  maintain  relative  posi- 
tion markers  within  the  scroll  bars.  The  markers  indicate 
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the  location  of  the  current  screen  within  a  larger  screen. 

CaUing  SS.SBar,  updates  both  scroll  markers. 

•  The  support  module  for  this  call  is  Windlnt. 
SS.Mouse 

(Function  code  $89).  Sets  the  sample  rate  and  button  timeout 
fiir  a  mouse 

Entry  Conditions: 

A     =  path  number 
B     =  $89 

X     =  mouse  sample  rate  and  timeoM 

most  significant  byte  =  mouse  sample  ra/te 
least  significant  bj^e  =  mouse  timeout 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  SS.  Mouse  allows  the  application  to  define  the  mouse 
parameters.  The  sample  rate  is  the  number  of  clock  ticks 
between  the  actual  readings  of  the  mouse  status. 

•  The  wm^iJ^at  module  for  the  call  is  CJC3I0. 
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SS.MsSig 

(Function  code  $8A).  Sends  a  signal  to  a  process  when  the 
mouse  button  is  pressed 

Entry  Oeuditions: 

A     =  path  number 
B      =  $8A 

X      =  user  defined  signal  code  (low  byte  only) 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  SS.MsSig  sends  the  process  a  signal  the  next  time  a  mouse 
button  changes  state  (from  open  to  closed).  Once  SS.MsSig 
sends  the  sipial,  ihe  p'ocess  must  repeat  the  Setstat  eadb 
time  that  it  needs  to     up  1^  signal. 

•  Processes  using  SS.MsSig  should  have  an  intercept  routine 
to  trap  the  signal.  By  intercepting  the  signal,  other  pro- 
cesses can  be  notified  when  the  change  occurs.  Therefore, 
the  other  processes  do  not  need  to  continually  poll  the 
mouse. 

•  The  SS.Relea  Setstat  clears  the  pending  signal  request,  if 
desired.  It  also  clears  any  pending  signal  from  SS.SSig. 
Because  of  this,  if  you  want  to  clear  only  one  signal,  you 
must  reset  the  other  signal  after  calling  SS.MsSig. 

•  The  support  module  for  this  c£ill  is  CC3I0, 
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SS.AScrn 

(Function  code  $8B).  Allocates  and  maps  a  high-resolution 
screen  into  an  application  address  space 

Entry  CoxtdiMcmsi 


A 

=  path  number 

B 

=  $8B 

X 

=  screen  type 

0  =  640  X  192  X  2  colors  (16K) 

1  =  320  X  192  X  4  colors  (16K) 

2  =  160  X 192  X  16  colors  (16K) 

3  =  640  X  192  X  4  colors  (32K) 

4  =  320  X  192  X  16  colors  (32K) 

Exit  Conditions: 


X      =  application  address  space  of  screen 
Y     =  screen,  number  (1-3) 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  SSAScrn  is  particularly  useful  in  systems  with  minimal 
memory  when  you  want  to  allocate  a  high  resolution  graph- 
ics sereea  wift  all  screen  mpdltting  handled  by  a  process. 

•  Hiis  call  uses  VDGInt  (GRFINT  is  not  required). 

•  All  screens  are  allocated  in  multiples  of  8K  blocks.  You  can 
allocate  a  maximum  of  three  buffers  at  one  time.  To  select 
between  bufif^s,  use  the  SS.DScm  Setstet  call. 

•  Screen  memory  is  allocated  but  not  cleared.  The  application 
using  the  screen  must  do  this. 

•  Screens  must  be  allocated  from  a  VDG-type  device — a 
standard  32-column  tesA  screen  must  be  available  for  the 
device. 

•  The  support  module  for  this  call  is  VDGINT. 
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SSJDScm 

(Function  code  $8C).  Causes  VDGINT  to  display  a  screen  that 

was  allocated  by  SS.AScrn 

Entry  Conditions: 

A      =  path  number 
B      =  $8C 

Y      =  screen  number  (1-3) 

Error  Output: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  ]bifbnnation: 

•  SS.DScrn  shows  the  reti3.egted  iereen  if  the  reqtiested 
screen  is  the  current  interactive  ^s^me. 

•  The  support  module  for  this  call  is  VDGINT. 
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SS.FScrn 

(Function  code  $8D).  Frees  the  memory  of  a  soreea  {lUocated 

by  SS.AScm 

Entry  Conditions: 

A      =  path  number 
B      =  $8D 

Y      =  screen  number  (1-3) 

Error  Output: 

CC  =  carry  set  on  error 
B     =  error  code  (if  any) 

Additional  tnfbnnation: 

•  Do  not  atteixipt  to  fsee  a  screen  that  is  currently  on  the 
display, 

•  SS.FScrn  returns  the  screen  memory  to  the  system  and 

removes  it  from  an  application's  address  space. 

•  The  support  module  for  this  call  is  VDGINT. 
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SB,FScm. 

(FunctiEm  fSE).  Conwts  a  screen  to  a  dif^ent  type 
Entry  Conditions: 


A 

=  path  number 

B 

=  $8E 

X 

=  new  screen  type 

0  =  640  X  192  X  2  colors  (16K) 

1  =  320  X  192  X  4  colors  (16K) 

2  =  160  X  192  X  16  colors  (16K) 

3  =  640  X  192  X  4  colors  (32K) 

4  =  320  X  192  X  16  colors  (32K) 

Y 

=  screen  number 

Error  Output: 

CC  =  csary  set  on  errcr 
B     =  &Tor  eoife  (if  any) 

AidilAcxiial  lofcHmiilion: 

•  SS.PScm  changes  a  screen  allocated  by  SS.AScm  to  a  new 

screen  type.  You  can  change  a  32K  screen  to  either  a  32K 
screen,  or  a  16K  screen.  You  can  change  a  16K  screen  only 
to  ano&er  16K  screen  type.  SS.PScm  updates  the  current 
display  screen  at  the  next  clock  interrupt. 

•  However,  if  you  change  a  32K  screen  to  a  16K  mmmi,  OS-9 
does  not  reclaim  mdim  16%  of  memory.  This  mmm 
that  you  can  lat^  change  the  16K  screen  back  to  a  32K 

screen. 

•  The  support  module  for  this  call  is  VDGINT. 
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SS-Monte 

(Functifm  eode  $92).  Sets  the  monitor  t3^ 

Entoy  Conditions: 

A      =  path  number 

B      =  $92 

X      =  monitor  type 

0  =  color  conq>osLte 

1  =  anabgl® 

2  =  monochronte  composite 

En*or  Oulput: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  SS.Montr  loads  the  hardware  palette  registers  with  the 
codes  for  the  default  color  set  for  three  types  of  monitors. 
The  system  default  initializes  the  psdette  for  a  composite 

•  The  mommhesme  mode  miciimm  eolsr  information  frcon  the 
signals  s^t  to  a  monitcxr. 

•  When  a  composite  monitor  is  in  use,  a  conversion  table 
maps  colors  from  RGB  color  numbers.  In  RGB  and  mono- 
chrome modes,  the  system  uses  the  RGB  color  numbers 
directly. 

•  The  support  modules  for  this  call  are  VDGINT  and  GrfDrv. 


8-146 


System  Calls  1 8 


SS.GIP 

(Function  code  $94).  Sets  the  system  wide  mouse  and  ki^ 

repeat  parameters 

Entry  Conditions: 

A      =  path  number 
B     =  $M 

X     =  mmms  resolution;  in  the  most  significant  hyte 

0  =  low  resolution  mouse 

1  =  optional  high  resolution  adapter 

=  mouse  port  location;  in  the  least  significant  byte 

1  =  right  port 

2  =  left  port 

Y      =  key  repeat  start  constant;  in  the  most  significant  hyte 
=  key  repeat  delay;  in  the  least  significant  \^te 
OOXX  =  no  repeat 
FFFF  =  unchanged 

Error  Output: 

GC  =  capry  set  if  eami 
B      =  error  code,  if  any 

Additional  Information: 

•  Because  this  function  affects  system-wide  settings,  it  is 
best  to  use  it  from  system  configuration  utilities  and  not 
frcsn  general  application  program. 

•  The  support  module  for  this  call  is  CC3I0. 
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SS.UMBAR 

(Function  code  $95).  Requests  the  high  levd  menu  mamsese  to 
update  the  menu  bar. 

Entry  Conditions: 

A      =  path  number 
B      =  $95 

Exit  Conditions: 

CC  =  carry  set  on  error 
B      =  error  code  (if  any) 

Additional  Information: 

•  An  application  can  call  SS.UMBar  when  it  needs  to  redmw 
menu  bar  information,  emh  m  whaa  it  eoaM^  or  ffisahles 
menus,  or  when  it  completes  a  window  pull  down  and  needs 
to  restore  the  menu. 

•  The  support  module  for  this  call  is  Windlnt. 
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SS.DFPal 

(Function  code  $97).  Sets  the  default  palette  register  values 

Entry  Conditions: 

A      =  path  number 
B  =$97 

X      =  poin^  to  16  bytes  of  palette  data 

Exit  Conditions: 

X     =  unchanged,  bytes  moved  to  system  defaults 
CC    =  carry  set  (Hi  error 
B     =  error  code  (if  any) 

AddiHonal  SnjEirmalion: 

•  Use  SS.DFPal  to  alter  the  system- wide  palette  register 
defaults.  The  system  uses  these  defaults  when  it  allocates  a 
new  screen  using  the  DWSet  command. 

•  Beeaxise  this  function  affects  system  wide  settings,  it  is 
best  to  use  it  from  system  configuration  utilities,  not  gen- 
eral application  programs. 
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SS.Tone 

(Function  code  $98).  Creates  a  sound  through  the  terminal 
output  dence. 

Enfa*y  Conditions: 

A     =  path  number 
B      =  $98 

X     =  dunxtton  and  ttmptitude  of  the  tone 

LSB  =  duration  in  ticks  (60-sec)  in  the  range  0-255 
MSB  =  amplitude  of  tone  in  the  range  0-63 

Y     =  relative  frequency  counter  (0  =  low,  4095 = high) 

Exit  Conditions: 

l^se  <a3m  l^e  dame  as  the  ^try  conditions.  Th^e  are  no 

error  conditions. 

Additional  Information: 

•  This  call  produces  a  programmed  10  tone  through  the 
speaker  of  the  monitor  used  by  the  iieea&mi  device,  'lai  can 
make  the  call  on  any  valid  path  open  to  term  or  to  a  win- 
dow device. 

•  The  system  does  not  mask  interrupts  during  the  time  the 
tone  is  being  produced. 

•  The  frequency  of  the  tone  is  a  relative  number  rangix^ 
from  0  for  a  low  frequency  to  4095  for  a  high  frequency. 
The  widest  variation  of  tones  occurs  at  the  high  range  of 
the  scale. 


Appendix  A 


Memory  Module  Diagrams 


Executable  Memory  Module  Format 


Relative 
Address 


Use 


—      §ync  Bytes  ($87,$CD) 


—       Modtile  Size  (l^ytes)  — 


' —        Module  Name  Offset 


Type 

Language 

Attributes 

Revision 

Header  Parity  Check 


Execution  Offset 


—     Permanent  Storage  Size 


(Additional  optional  header 
ext@tmiE8is  located  here) 


Module  Body 
object  code,  constants, 
and  so  on 


Check 
Range 


header 
parity 


module 
CRC 


ORG  Check  Value 
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Device  Descriptor  Format 


Relative 
Address 

$00 


Use 


Check 
Range 


—    Sync  Bytes  ($87,$CD)  — 


—     Module  Size  (bytes) 


—  Offset  to  Module  Name  — 


$0D 
$0E 

$0F 

$10 
$11 

$12,$l2  +  i 


$F  (Type) 


Attributes 


$1  (Lang) 


Revision 


Header  Parity  Check 


Offset  to  File  Manager 
Name  String 


Offset  to  Device  Driver 
Name  String 


Mode  Byte 


Device  Controller 
Absolute  Physical  Addr. 
(24  bit) 


Initialization  Table  Size 


(Initialization  Table) 


(Name  Strings,  and  so  on) 


CRC  Check  Value 


header 
parity 


Module 
CRC 
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JNIT  Module  Format 


Relative 
Address 


Use 


Check 
Range 


$00 

$01 

—      §ync  Byt 

es  {|87,$GD)  — 

$02 
$03 

—       Module  Size  G^es)  — 

$04 

—       M}dule  Name  Offset  — 

ipUb 

$F  (Type) 

$1  (Lang) 

$07 

Attributes 

Revision 

!))Uo 

Header  Parity  Check 

$09 
$0A 

—        Forced  Limit  of  Top  — 
of  Free  RAM 

$0B 

$0C 

#IRQ  Polling  Tabk  Intxies 

$0D 

#Device  Ikitdes 

$0E 

$0F 

—        Offset  to  Startup  — 
Module  Name  String 

$10 
$11 

—      Offset  to  Default  Mass  — 
Storage  Device  Name  String 

$12 
$13 

—         Offset  to  Bootstrap  — 
Module  Name  String 

$14-n 

Name  Strings 

ORG  Check  Value 

header 

parity 


Module 
CRC 
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Standard  Floppy  Disk  Format 


Color  Computer  3 


Bbmat  

Header  pattern 
(once  per  track) 


Sector  pattern 
(repeated  18  times) 


Trailer  ■pm.Uem 
(once  per  track) 


Bytes 

Value 

(Dec) 

(Hex) 

32 

4E 

12 

00 

3 

F5 

1 

FC 

32 

4E 

12 

00 

3 

F5 

1 

track  number  (0-34) 

1 

side  number  (0-1) 

1 

sector  number  (1-18) 

1 

sector  length  code  (1) 

2 

CRC 

22 

4E 

12 

00 

3 

F5 

1 

FB 

256 

data  area 

2 

CRC 

24 

4E 

N 

4E  (fill  to  index  mark) 
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Appendix  C 


System  Error  Codes 


The  error  codes  are  shown  in  both  hexadecimal  and  decimal.  The 
error  codes  listed  include  OS-9  system  ecmr  codes,  BASIC  error 
codes,  and  standard  windowing  system  error  codes. 

Code       Code  Meaning 
HEX  DEC 

$01  001  UNCONDITIONAL  ABORT  —  An  error  occurred 
from  which  OS-9  camiot  recover.  All  processes 

are  terminated. 

$02  002  KEYBOARD  ABORT  —  You  pressed  FbreakI  to 
tmninate  the  current  operation. 

$03  003  KEYBOARD  INTERRUPT  —  You  pressed 
I  SHIFT  II  break]  either  to  cause  the  current  operation 
to  function  as  a  background  task  with  no  video 
displ£^  or  to  cause  the  current  task  to  terminate. 

$B7  183  ILLEGAL  WINDOW  TYPE  —  You  tried  to 
define  a  text  type  window  for  graphics  or  used 
il 


$B8  184  WINDOW  ALREADY  DEFINED  —  You  tried  to 
OT^te  a  window  that  is  sicm^  established. 

$B9  185  FONT  NOT  FOUND  —  You  tried  to  use  a  win- 
dow font  that  does  not  exist. 

$BA  186  STACK  OVERFLOW  —  Your  process  (or  pro- 
cesses) requires  more  stack  space  than  is  avail- 
able on  the  system. 

$BB  187  ILLEGAL  ARGUMENT  —  You  have  used  an 
argum^t  with  a  command  that  h  Ixmppctspnate. 

$BD     189      ILLEGAL  COORDINATES  —  You  have  given 

coordinates  to  a  graphics  command  ^lich  are 

outside  the  screen  boundaries. 

$BE  190  INTERNAL  INTEGRITY  CHECK  —  System 
modules  or  data  are  changed  and  no  longer 

reliable. 

$BF  191  BUFFER  SIZE  IS  TOO  SMALL  —  The  data  you 
assigned  to  a  buffer  is  larger  than  the  buffer. 
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$C0  192 

$C1  193 

$C2  194 

$C3  195 

$G4  196 

$C8  200 

$C9  201 

$GA  202 

$CB  203 

$CC  204 

$CD  205 

$CE  206 


Code  Meaning 

ILLEGAL  COMMAND  —  You  have  issued  a 
command  in  a  form  unacceptable  to  OS-9. 

SCREEN  OR  WINDOW  TABLE  IS  FULL  —  You 
do  not  have  mmtgh.  room  in  the  system  vrindow 
table  to  keep  track  of  any  more  windows  or 

screens. 

BAD/UNDEFINED  BUFFER  NUMBER  —  You 
have  specified  an  illegal  or  undefined  buffer 

number. 

ILLEGAL  WINDOW  DEFINITION  —  You  have 


tried  to  give  a  window  illegal  jiarameters. 

WIOTOW  UNDEFliffiB  —  hmm  mi  to 
access  a  window  that  you  1mm  mb  y©l  d^lotd. 

PATH  TABLE  FULL  —  OS-9  cannot  open  the 
file,  because  the  system  path  table  is  full. 

ILLEGAL  PATH  NUMBER  —  The  path  number 
is  too  l£tr^,  or  you  specified  a  non-existent  path. 

INTERRUPT  POLLING  TABLE  FULL  —  Your 
system  cannot  handle  an  interrupt  request, 
because  ihs  pdlixig  table  does  nt^  have  room  for 
iaore  entries. 

ILLEGAL  MODE  —  The  specified  device  cannot 
perform  the  indicated  input  or  output  function. 

DEVICE  TABLE  FULL  —  The  device  table  does 
not  have  ^uaigh  roffln  fi)r  another  device. 

ILLEGAL  MODULE  HEADER  —  OS-9  cannot 
load  the  specified  module  because  its  sync  code, 
hm4sat  parity,  or  OycUc  Eedmnda&ey  Code  is 
incorrect. 

MODULE  DIRECTORY  FULL  —  The  module 
directory  does  not  have  enough  room  for  another 
tnodule  entry. 
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Code       Code  Meaning 

HEX  tmc 

$CF  207  MEMORY  FULL  —  Process  address  space  is  full 
or  your  computer  does  not  have  sufficient  memory 
to  perform  the  specified  task. 

$D0  208  ILLEGAL  SERVICE  REQUEST  —  The  current 
program  has  issued  a  system  call  containing  an 
illegal  code  number. 

$D1  209  MODULE  BUSY  —  Another  process  is  abeady 
using  a  non-^reable  module. 

$D2  210  BOUNDARY  ERROR  —  OS-9  has  received  a 
memory  allocation  or  deallocation  request  that  is 
not  on  a  page  boundary. 

$D3  211  END  OF  FILE  —  A  read  operation  has  encoun- 
tered   an    end-of-file   character   and  has 

terminated. 

$D4  212  RETURNING  NON-ALLOCATED  MEMORY  — 
The  current  operation  has  attempted  to  deallo- 
cate memory  not  previously  assigned. 

$D5  213  NON-EXISTING  SEGMENT  —  The  file  struc- 
ture of  the  specified  device  is  dainagiid. 

$D6  214  NO  PERMISSION  —  The  attalbates  of  the  speci- 
fied file  or  device  do  not  permit  the  requested 

access. 

$D7  215  BAD  PATH  NAME  —  The  specified  pathlist  con- 
tains a  syntax  error,  for  instance  an  illegal 

character. 

$D8  216  PATH  NAME  NOT  FOUND  —  The  system  can- 
not find  the  specified  papist. 

$D9  217  SEGMENT  LMT  FULL  —  The  ^^dfied  file  is 
too  fragmented  for  further  expansion. 

$DA  218  FILE  ALREADY  EXISTS  —  The  specified  file- 
name already  exists  in  the  specified  directory. 

$DB  219  ILLEGAL  BLOCK  ADDRESS  —  The  file  struc- 
ture of  the  specified  device  is  damaged. 


OS-9  Technieal  JReference 


$DC  220 

$DD  221 

$DF  223 

$E0  224 

$E2  226 

$E3  227 

$E4  228 

$E5  229 

$E6  230 

$E7  231 

$E8  232 

$E9  233 

$EA  234 


Code  Meanu^ 

PHONE  HANGUP-DATA  CARRIER  DETECT 
LOST  —  The  data  carrier  detect  is  lost  on  the 
RS-232  port. 

MODULE  NOT  FOUND  —  The  system  received 
a  request  to  link  a  module  that  is  not  in  the 
specified  directoy. 

SUICIDE  ATTEMPT  —  Tbs  current  operation 
has  attempted  to  return  to  the  memory  location 
of  the  stack. 

ILLEGAL  PROCESS  NUMBER  —  The  specified 
process  does  not  exist. 

NO  CHHiDEEN  —  The  sysliffla.  has  issued  a  wait 
service  request  but  the  current  {arocess  has  no 
dependent  process  to  scecute. 

ILLEGAL  SWI  CODl  —  The  system  received  a 
software  interrupt  code  that  is  less  ihan.  1  or 

greater  than  3. 

PROCESS  ABORTED  —  The  system  received  a 
si^al  Code  2  to  terminate  the  current  process. 

PiK)ClSS  TABLE  PULL  —  A  fork  request  can- 
not execute  because  the  process  table  has  no 
room  for  more  entries. 

ILLEGAL  PARAMETER  AREA  —  A  fork  call 
has  passed  incorrect  high  and  low  bounds. 

KNOWN  MODULE  —  The  specified  module  is 

for  internal  use  only. 

INCORRECT  MODULE  CRC  —  The  CRC  for  the 
module  hekm  accessed  is  bad. 


SIGNAL  EKROE  —  The  receiving  process  has  a 

previous,  unprocessed  signal  pending. 

NON-EXISTENT  MODULE  —  The  system  can- 
noi  locate  the  specified  module. 


System  Error  Codes  I C 


Code       Code  Meaning 
HEX  JMC 

$EB     235      BAD  NAME  —  The  specified  device,  fik,  or  mod- 
ule name  is  illegal. 

$EC     236      BAD  MODULE  HEADER  —  The  specified  mod- 
ule header  puriit^  is  incorrect. 

$ED     237      RAM  FULL  —  No  free  system  random  access 

memory  is  available:  the  system  address  space  is 
full,  or  there  is  no  physical  memory  available 
when  requested  by  the  operating  system  in  the 

system  state. 

$EE     238      UNKNOWN  PROCESS  ID  —  The  specified  pro- 
cess ID  niunber  is  incorrect. 

$EF     239      NO  TASK  NUMBIR  AmiLABLE  —  All  avail- 
able task  numbers  are  in  xise. 


Device  Driver  Errors 


I/O  device  drivers  generate  the  following  error  codes.  In  most 
cases,  the  codes  are  hardware-dependent.  Consult  your  device 
manual  for  more  details. 


Code 
HEX  DEC 

Code  Meaning 

$m 

240 

UNIT  lERO®  —  The  spetiiled  device  unit 
doeasni;  adst. 

$F1 

241 

SECTOR  ERROR  —  The  specifiral  sector  number 

is  out  of  range. 

$F2 

242 

WRITE  PROTECT  —  The  specified  device  is 
write-protected. 

$F3 

243 

CRC  ERROR  —  A  Cyclic  Redundancy  Code  error 

occurred  on  a  read  or  write  verify. 

$F4 

244 

READ  ERROR  —  A  data  transfer  error  occurred 
duuri^  a  disk  read  operation,  or  there  is  a  SCF 
(termhial)  input  buffer  overrun.  . 
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Code       Code  Meaning 
MMM.   IM  C 

$F5     245      WRITE  ERROR  —  An  eror  occurred  dviring  a 

write  operation. 

$F6  246  NOT  READY  —  The  device  specified  has  a  not 
ready  status. 

$F7  247  SEEK  ERROR  —  The  system  attempted  a  seek 
operation  on  a  non-existent  sector. 

$F8  248  MEDIA  FULL  —  The  speafied  media  has  insuf- 
ficient free  sgmm  Sm  t&e  t^^msMm. 

$m  249  WE(MG  TYPE  —  An  attempt  is  made  to  reiBl 
incompatible  media  (for  instance  an  attempt  to 
read  double-side  disk  on  single-side  drive). 

$FA  250  DEVICE  BUSY  —  A  non-shareable  device  is  in 
use. 

$FB     251      DISK  ID  CHANGE  —  You  changed  diskettes 

when  one  or  more  files  are  open. 

$FC     252      RECORD  IS  LOCKED-QUT —  Another  process 

$FD  253  MM-SHAKMU!  FILE  MMT  —  Another  pro- 
cess is  accessing  tibe  teciimiled  file. 

$FE  254  I/O  DEADLOCK  ERROR  —  Two  processes  have 
attempted  to  gain  control  of  the  same  disk  area 
at  the  same  time. 


C-6 


Index 


ACIAPAK  8-135 

active  process   2-12  -  2-13 

queue   2-14,  8-98 

state   2-13  -  2-14 
address 

find  64K  block  8-85 

lines  2-7 

polling  2-17 

space,  add  module  8-104 
age,  process  2-14 
alarm,  set  8-66 
allocate 

high  RAM  8-69 

imi^  8-70 

memory  8-76 

memory  blocks   8-67  - 
8-68 

process  descriptor  8-71 

process  task  numbea* 
8-73 

RAM  8-72 
allocation 

bit  map  8-7 

map  sector  5-1 

of  memory   2-5  -  2-7 

polling  2-17 
allocatioii  map 

ete  8-13 

disk  5-3 
alpha  screen 

cursor  8-118 

memory  8-117 
ASM  assembler  8-2 
assembler,  RMA  8-2 
attach  a  device    8-44  -  8-45 
attribute 

byte  5-5, 

file  5-12 

background  color,  get  8-129 
bell,  set  alarm  8-66 
bit  map  2-5 

allocatkm  8-7 


bit  map  (cont'd.) 

search  memory 
allocation  8-33 

block 

allocate  system 
meanory  8-105 

deallocate  system 
memory  8-106 
map  into  process 

space  8-96 
number  2-7  ■ 
scroll  8-139 
block  map,  system  8-18 
boot 

file,  load  5-26 

module,  link  8-75 
booting  OS-9  1-3 
bootstrap 

memory  request  8-76 

system  8-75 
bwder  color,  get  8-129 
buffer 

map  (Get/Put)  8-138 

reserve  graphics  8-136 
button 

state,  mouse    8-124  - 
8-125,  8-126 

timeout,  mouse  8-140 

byte 

attribute  5-5 
deallocate  64-byte 

block  8-101 
get  from  memory 

block  8-94 
get  two  bytes  8-95 
read  from  path    8-59  - 

8-60 

store  in  task  8-109 

calling  process 

insert  in  I/O  queue  8-91 
terminate  8-14 
turn  off   8-35,  8-43 

CC3DISK  1-2 
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CC3G0  module  2-19 
CC3I0  1-2,6-1 
chain  8-8  -  8-9 
change 

de^Ce  operating 
parameters  5-23 

directory  8-46 
character 

read  SCF  input  6-13 

write,  SCF  6-14 
ChgDir  4-4 
child  process  2-13 

create   8-15  -  8-17 
clear  specified  block  8-77 
click  8-126 
CLOCK  1-2 
clock 

module    1-2,  2-19 
real-time  2-12,2-17 

close 

file  4-7 

path  8-47,8-135 
codes 

signal  2-15 
system  error  C-1 
command  interpreter  1-4 
communication, 

interpmiee  i-lS 
compact  module  directory 
8-88 

compare  strings  8-10 
compatibility  with  Le^^ 

One  2-1 
concurrent  execution   7-1  -  7-3 
copy  external  memory  8-11 
count,  link  2-5 
counter  start,  mouse  8-124 
CPU  2-7 

time  4-11 

CRC 

calculate  8-12 
validate  module  8-111 
value   3-1  -  3-3 
create 

directory   8-55  -  8-56 


create  (cont'd.) 

file  8-48-8-49 

current 

data  directory  8-51 
exectitlwi  directory  8-81 

cursor  positioning  4-5 

cyclic  redundancy  check   3-1  - 
3-3 

DAT 

hardware  8-99 
registers  8-103 
to  logical  address  8-78 

data 

available,  SCF  test 

8-113 
directory  8-51 
stream  4-3 

transfer,  pipes   7-1  -  7-3 

move  in  memory  8-97 
DAT  image  8-70 

conversion  8-78 

copy  into  process 
descriptor  8-102 

deallocate  block  8-77 

high  block  8-86 

low  block  8-87 

poiHter  8-95 
DAT  task  number 

release  8-99 

reserve  8-100 

date 

get  sjmtem  8-40 

set  8-38 
deadlock  5-13 
deadly  embrace  5-13 
deallocate 

image  RAM  blocks  8-79 

map  bits  8-13 

process  descriptor  8-80 

RAM  blocks  8-81 

task  number  8-82 
de&ult  palette  re^sters 

8-129,  8-149 
delete  file  8-50-8-51 


2 


descriptions,  system  call  8-2 
descriptor 

get  process  8-20 
path  4-18 
pointer  8-82 
p-ocess  2-13 
detacb  device  8-52 
device 

add  or  remove  from 

polling  table  8-92 
attach   8-44  -  8-45 
attachment,  verify  8-44 

-  8-45 
controller  5-15 
control  registers, 

initialize  6-12 
control  registers,  SCF 
6-12 

descriptor    1-4,  4-2,  4-17, 

A-2 
detach  8-52 
modules  5-15 
modules,  RBF    5-8  -  5-10 
modules,  SCF  6-6-6-8 
name,  get  8-115 
open  path  to    8-57  -  8-58 
operating  peirameters, 

RBF  5-23 
operating  parameters, 

SCF  6-15 
status   2-17  -  2-18,  8-63 
status,  get  8-54 
table   4-2,  8-52 
terminate,  RBF  5-24 
terminate,  SCP  6-16 
write  to   8-64  -  8-65 
device  driver    1-3,  4-11 
close  path  8-135 
modules  4-8 
name  5-15 
SCF    6-9  -  6-17 
SCF  subroutines    6-10  - 

6-17 

subroutines,  RBF   5-16  - 
5-27 


device  driver  modules, 

RBF   5-13  -  5-17 
device  interrupt  5-25 

SCF  6-17 
directory 

attribute  byte  5-5 

change  8-46 

disk  5-5 

entry,  module  8-83 
get  module  8-19 
make   8-55  -  8-56 
module   2-12,  8-88 

disk 

directories  5-5 
sector  read  5*19,  5-21 

disk  allocation  map  5-3 
sector  5-1 

diskette  fcmnat  B-1 

display 

screen  8-143 
status,  get  8-115 

drag  8-126 

drive  head,  restore  8-181 
duplicate  path  8-53 

editing,  line    6-1,  8-61 
end-of-file,  test  for  8-114 
equate  file  2-4 
equivalent  logical  address 

8-78 
error 

codes,  system   C-1  -  C-6 

message,  write  8-30 

print  8-30 
exclamation  point,  pipes    7-1  - 

7-3 
execute 

mode  5-11 

system  calls  8-1  -  8-2 
execution 

directory  8-51 

offset,  module  3-7 
exit  calling  po^S  8-14 
external  memory,  read  8-11 
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&tal  signal  2-13 
Wb 

attribute  byte  5-12 

closing  4-7 

create   4-4,  5-12,  8-48  - 

8-49 
deadlock  5-13 
delete   4-5,  8-50  -  8-51 
descriptor   5-3  -  5-4 
execute  mode  5-11 
get  pointer  position 

8-114 

line  reading/writing  4-6 
load  module  8-29 
locking  5'12 
non-shareable  5-12 
opening  4-4 
open  path   8-57  -  8-58 
permission  bits  5-4 
pipe   f-1  -  7-3 
pointer   4-5,  8-62 
position,  RBF  8-114 
read  5-1,  4-5 
sharing  5-12 
size,  get  8-114 
status,  get    8-54,  8-114 
update  mode  5-11 
write  line  to   8-64  -  8-65 
writing  4-6 
file  manager  1-3 
modules  4-3 
name  5-15 

find 

64-byte  block  8-85 

module  directory 
entry  8-84 
fire  button   8-123  -  8-127 
PIRQ  4-12 

interrupt  2-17 
flag,  RAM  In  Use  8-81 
flip  byte  2-17 
floppy  diskette  format  B-1 
foreground  color,  get  8-129 
FORK  2-8 

fork,  child  process   8-15  -  8-17 


FORMAT  5-2 
format 

device  desciiptoi*  4-17, 
A-2 

13OTr»iule  A-3 
memory  module  3-6  - 

3-7, A-1 
of  device  driver 

modules  4-10 
track  8-132 
fimction 

calls   2-4  -  2-5,  8-1 
key  sense  8-133 

gst 

a  bybe  8-94 
ft-ee  high  block  8-86 
free  low  block  8-87 
ID  8-22 

process  pointer  8-89 

status  8-54 

Status  system  calls 
8-112  -  8-130 

system  time  8-40 
Get/Put  buffer,  map  8-138 
GETSTA  8-112 

SCF  6-15 
GetStat  4-6 
Getstats  5-23 
graphics  buffer 

reserve  8-136 

select  8-137 
graphics  interface  1-2 
GRFINT  1-2 

handler  routine,  virtual 

interrupt  8-110 
hard  disk  shutdown  8-133 
hardware 

controller,  SCF  6-9 

DAT  registers  8-103 

vector  2-16 
header 

module   3-1  -  3-2 

parity  8-Xll 
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header  (cont'd.) 

pattern,  floppy 
diskette  B-1 

high  block,  memory  search 
8-86 

high-level 

menu  handler  8-122 
menu  manager  8-148 
window  handler  8-139 

high-resolution 

mouse  adapter  8-126 
screen,  allo^te  8-142 

hold,  button  8-126 

I/O 

calls  2-4-2-5,8-1 
device  accessing  2-11 
module,  delete  8-90 
path,  close  8-47 
queue,  insert  calling 

in-oeess  8-91 
I/O  system    1-3  -  1-4 
calls   2-1,  8-2 
system  modixles   1-1  - 

1-4,  4-1 
transfers  4-8 

ID 

return  caller's 

process  8-22 
set  user  8-39 
identification  sector  5-1 
image,  allocate  8-70 
INIT    1-2,  5-18 
INIT  module  2-17 
format  A-3 
link  8-75 
Init,  SFC  6-12 
initialization  table,  SCF 

device    6-6  -  6-8 
initialize  device  itmomy  5-18 
input  buffer,  read  SCf 

character  6-13 
insert  process  8-74 
install  virtual  interrupt 
8-110 

intercept,  set  signal  8-21 


interface 

graphics  1-2 

VDG  4-2 

Windmt  4-2 
interprocess 

communication  2-15 
intmnipt 

device  5-25 

enable,  SCF  6-12 

FIRQ  2-17 

processing  2-1 
lOMAN  1-2 
IRQ  4-12 

add/remove  device  from 
polling  table  8-92 

interrupt  2-17 

polling  2-17 

polling  table  2-18 

service  routine  5-25 
IRQSVC  routine  4-13 
IRQSV  4-11 

joystick  value,  get  8-116 

kernel  1-2 
k^ 

repeat  parameters, 

set  8-147 
sense  function  8-133 
status,  get  8-120 
keyboard  scan  2-17 

language  byte  3-4 
line 

editing  6-1,8-61 

reads    4-6,  8-61 
writes    4-6,  8-65 

link 

to  memory  module  8-23 

-  8-24,  8-28 
using  module  directory 

entry  8-83 
link  count  2-5 

decrease  8-42 


OS -9  Technical  Reference 


boot  file  B'M 
byte  from  memory 

block  8-94 
from  task  offset  8-93 
module   8-25  -  8-26,  8-29 
two  bytes  S-iB 

lock,  end-of-tock  5-12 

locking 

files  5-12 

record   5-10  -  5-11 

logical 

address  space    2-6,  2-8 
sector  nxmiber  5-1 

LSN  5-2,5-5 

macro  2-4 

MAKDIR  4-4 

make  directory   8-55  -  8-56 

manager 

file  1-3 

random  block  1-3 
sequential  file  1-3 

map 

block  8-96 

search  allocation  8-33 
mask  byte  2-18 
memory 

allocate  8-76 

allocate  blocks  8-67  - 
8-68 

allocate  high  RAM  8-69 
change  process  data 

size  8-27 
deallocate  2-S 

find  low  block  8-87 
free  screen  8-144 
map  2-6 

module  format   3-6  -  3-7, 
A-1 

module,  link    8-23  -  8-24 
move  data  8-97 
page  2-5 
pool  8-80 

requ^l,  bosfetkat  8-f8 


memory  (cont'd.) 

segmesit  2-8 
memory  allocation   2-5  -  2-7 
memory  block  2-7 

fmd64K  8-85 

get  byte  8-94 

get  high  8-86 

map  8-81 

map,  search  8-72 
memory  management  2-1,  2-5 
-  2-12 

unit  2-7  -  2-8 
menu 

manager,  update 
request  8-148 

selection  8-122 
message,  write  error  8-30 
MMU  registers  2-8 
mnemonic  name,  LSN  5-2 
MODPAK  8-135 
module 

add  into  address 
space  8-104 

body   3-1  -  3-2 

clock  2-19 

CRC  calculate  8-12 

decrease  link  count  8-42 

delete  I/O  module  8-90 

device  descriptor  5-15 

device  diAv&  4-8 

file  manager  4-3 

finding  2-12 

format   3-1  -  3-3 

link  8-28 

link  ccnlnt,  decrease 
8-42 

linking  1-2 

load   8-25  -  8-26,  8-29 

load  and  execute 
primary  8-8  -  8-9 

name  3-3 

RBF-type  device 

drivers   5-13  -  5-17 

SCF  device  descriptor 
6-6  -  6-8 
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module  (cont'd.) 

types    3-1,  3-5 

unlink  8-41 

validate  8-111 
module  direetetry  2-5,  2-12 

compact  8-88 

entry,  link  using  8-83 

find  8-84 

get  8-19 

pointer  8-84 
module  header    3-1  -  3-3,  5-15 

SCF  device  driver  6-9 
tmalm,  set  tj^e  8-146 
mouse 

button  state  8-125 

button  timeout  8-140 

click  8-122 

coordinates  8-127 

countdown  8-125 

countup  8-125 

parameters,  set  8-147 

port  8-125 

resolution  8-126 

screen  position  8-126 

send  signal  to  process  8- 
141 

status,  get  8-123 
timeout  8-124 
window  working  area 
8-127 
move  data  8-97 
multiplexer  2-8 
tnaltipfOgraBnHing  2-12  - 
2-16 

management  2-1 
multitasking  1-2 

niame  parse  8-31  -  8-32 

names,  compare  8-10 
next  process  8-98 
NMI  interrupt  2-17 
non-shareable  file  5-12 
numb^,  ptth  8-53 


open 

file    8-48  -  8-49 

path   8-57  -  8-58 
op^ation  of  voeamy 

managemrait  2«8  -  2-12 
OS-9 

Level  One 

compatibility  2-1 
modules  1-2 
sehedtiler  2-14  -2-15 
OS9P3  2-1 

module  2-2 

packet  size  8-124 

palette,  get  information  8-127 

palette  register  8-129 

set  default  8-149 

settii^  3-129 
parameters,  mouse  and  key 

repeat  8-147 
parent 

directory  5-3 

process  2-13 
parity  8-135 
parse  name   8-31  -  8-32 
path 

close   8-47,  8-135 
teplicate  S-m 
open    8-57  -  8-58 
read  bytes    8-59  -  8-60 
table  4-2 
path  descriptor   4-18,  5-5  - 
5-8 

read  option  section 

8-112 
SCF  6-2-6-6 
write  option  section 

8-130 

permanent  storage  size, 

module  3-7 
physical  address  space  2-7 
pipe  file  manager  4-3 
EMWN  l-i  -l-i,4-3 
pipes   4-3,  7-1  -  7-3 


OS-9  HkeM^  Befsrmce 


process  descriptor   2-13  - 
2-14,  8-102 

deallocate  8-80 

descriptor,  albcate  8-71 

get  8-20 

pointer  8-82 
processes 

active  2-12 

data  size,  change  8-27 
process  ID  2-13 

return  caller's  8-22 
pseudo  vector  2-16 
PutStat  4-6 

RAM  2-5-2-7 

allocate   8-69,  8-72 

allocate  blocks  8-70 

allocation  2-13 

blocks,  deallocate  8-81 

blocks,  deallocate 
image  8-79 

interrupt  vector  2-18 
random 

access  5-1 

block  file  manager  1-3, 
4-3 

RBF 

change  file  size  8-131 
format  track  8-132 
get  file  size  8-114 
manager  4-3 
tables  5-14-5-17 

read 

bytes    8-59  -  8-60 

device  operating 
parameters  5-23 

di^  sector  5-19 

es:teaial  ateEDory  8-11 

input  character,  SCF 
6-13 

line   6-2,  8-61 

mode  5-11 

system  call  6-1 
real-time  clock   2-12,  2-17 
record  locking  5-10 


reference 

System  Mode  calls   8-5  - 
8-6 

User  Mode  system 
calls  8-3  -  8-4 
registers 

DAT  8-103 
MMU  2-8 
release  a  task  8-99 
request  system  memory 
8-105 

reserved  memory   2-5  -  2-7 
reserve  task  number  8-100 
return 

64  bytes  8-101 
system  memory  8-106 
RMA  assembler  8-2 
ROOT  directory  5-3,  5-5 
RTS  instruction  2-18 

SCF 

configure  serial  port 
8-184  -  8-liS 

data  available  test 

8-113 
device  control 

Getsta  6-lS 

manager  4-3 

path  descriptor   6-2  -  6-6 

terminate  device  6-16 
scheduler,  OS-9  2-14-2-15 
SQ^eti 

allocate  high- 
resolution  8-142 

convert  type  8-145 

display  8-143 

free  metnoiy  8-144 

mouse  position  8-126 

palette  8-127 

size,  get  8-119 

type  8-128,8-142,8-145 
seroQ  W>tk^  insMI  8-139 
search  bits  8-33 
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Index 


sector  5-3 

pattern,  floppy 
diskette  B-1 
seek,  file  pointer  8-62 
segment,  memory  2-8 
select  graphics  bu£^  8-137 
send  signal  8-34 
sequential  character 

file  manager    1-3,  4-3 

I/O  6-1 
serial  port  configuration 

8-121 
service 

request  processing  2-1 

routine,  IRQ  5-25 

set 

alarm  8-66 
date  8-38 
IRQ  8-92 
pdca%  3-3  6 
process  DAT  image 

8-102 
process  task  DAT 

repsters  8-103 
status  8^63 
SVC  8-107-8-108 
SWI  8-37 
time  8-38 
user  ID  8-39 
Setstats  6-23 

Set  Status  system  calls  8-130 

-  8-150 
shareable  bit  3-5 
sharing,  file  5-12 
shell  1-4 

shutdown  hard  disk  8-133 
signal  2-15-2-16 
codes  2-15 
fatal  2-13 
from  mouse  to 

process  8-141 
intercept  trap    2-15  - 
2-16 

intercept,  set  8-21 
send  to  process  8-34 


single-user 
attritetse 
bit,  files  5-12 

size 

of  screen  8-119 
of  window  8-119 

sleep 

calling  process  8-35 
sleeping  process    2-14,  2-16 
slices,  time  2-12 
sound,  create  8-150 
speaker,  create  sound  8-150 
state 

active  2-13 

of  button  8-12« 

sleeping  2-14 

suspend  4-13 

waiting  2-13 
static  storage  address  2-18 
status 

display  8-115 

get,  SCF  6-15 

get  mouse   8-123  -  8-127 

of  key  8-120 

register  2-17 

set,  SCF  6-15 
status,  get  8-54 
status,  set  8-63 
store  byte  in  a  task  8-109 
string,  scan  input   8-Sl  -  §'-32 
strings,  compare  8-10 
subroutines 

RBF  device  driver  5-16  - 
5-27 

SCF  device  drivers  6-10 
-  6-17 

suspend 

bit    4-13  -  4-14 

state  4-13 
SWI,  set  8-37 
SWI2  instruction  2-4 
symbolic  names  2-4 
3-3 

w^mmgmeim  path  number, 
rettum  8^53 


9 


OS-9  Tkchnieal  Reference 


Systran 

block  map,  get  8-18 
boot  1-3 
bootstrap  8-75 
date,  get  8-40 
device,  attach  8-44 
error  codes  C-1  -  0-6 
initialization  2-1 
link  8-104 

mode  call  r^reoce   8-5  - 
8-6 

time,  get  8-40 

system  call 

add   8-107  -  8-108 
descriptions   8-2,  2-4 
execution   8-1  -  8-2 
get  status   8-112  -  8-130 
mnemonics  names  8-1 
User  Mode  reference  8-3 
-8-4 

system  memory 

allocate  high  RAM  8-69 
block  map  8-81 
deallocate  8-106 
module  directory,  get 

8-19 
request  8-105 

system  modules   1-1  - 1-4 

table 

device  8-52 
IRQ  polling  2-18 
RBF  5-14-5-17 
SCF  device  descriptor 

6-6  -  6-8 
VmQ  2-20 

task 
•    map  2-12 

offset,  load  from  8-93 

register  2-8 

release  8-99 

store  byte  8-109 
task  number  8-73 

DAT  8-100 

dieallocate  8-82 


terminal,  create  sound  8-150 

terminate 

a  device  5-24 
calling  process  8-14 
SCF  device  6-16 

ticks  4-11 

tjme 

CPU  4-11 

get  system  8-40 

set  8-38 

sharing  2-11 

slice  2-16, 2-11 
timeout,  mouse  8-124 
track 

fitrmat  8-132 

restore  drive  head  8-131 
trailer  pattern,  floppy 

diskette  B-1 
trap,  signal  intercept   2-15  - 

2-16 
type 

convert  screen  8-145 
of  screen  8-128 
set  mcmitor  8-146 
window  seareen  8-142 

unlink  module    8-41  -  8-42 
update  mode  5-11 
us0r  calls  2-5 
user  ID  2-13 
set  8-39 
User  Mode  system  calls 
reference  8-3  -  8-4 

validate  module  8-111 
VDG  1-2 

alpha  screen  cursor 
8-118 

alpha  screen  memory 
8-117 

interfeice  4-2 
vector 

pseudo  2-16 

setSWI  8-37 
vectoring  2-16 
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/ndlex 


verify  device  attachment 

8-44  -  8-45 
video  display  generator  1-2 
VIRQ  2-19-2-20 

polling  taMe  2-19-2-20 
virtual  interrupt,  install 

8-110 

wait 

calling  process  S-43 
state    2-13  -  2-14 

waiting  process  2-13 

wildcard  4-6 

WINDINT  1-2 

Windint  interfece  4-2 

wiixdow 

descriptors  1-2 
high-level  handler  8-139 
pointer  location  8-124 
screen,  type  8-142 
size,  get  8-119 
type  8-145 
working  area,  mouse 
8-127 


working  directory,  change 

8-46 
write 

character  to  SCF 

output  6-14 
disk  sector  5-21 
path  descriptor   8-130  - 

8-131 

to  file  or  device  8-64 
write  line  8-6S 

line  system  call  6-2 
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Types  of  OS-9  Windows 


Unlike  many  operating  systems,  OS-9  has  a  built-in  windows 
program.  This  driver,  the  Windowing  System,  lets  you  lay  one  or 
more  smaller  screen  displays,  called  windows,  on  your  screen 
display. 

With  these  windows,  you  can  perform  several  tasks  at  the  same 
time.  For  example,  suppose  you  are  writing  a  business  letter 
using  a  word  processor  in  one  window.  'You  can  go  to  a  spread- 
sheet program  in  another  window,  get  a  price  quote  you  need, 
return  to  the  -word  processor,  and  include  the  xirice  in  the  letter. 

The  Windowing  Slystem  allows  as  many  windows  as  your  com- 
puter's memory  can  support,  with  a  maximum  of  32  at  one  time. 

In  OS-9,  there  are  two  types  of  windows:  device  and  overlay. 

Device  Windows 

A  device  window  is  one  that  can  run  a  program  or  utility.  This 
is  tile  type  of  window  you  would  use  in  the  word  processor/ 
spr^ulsheet  example  given  above.  Each  device  window  acts  as  an 
indiviiiial  terminaL 

The  device  windows  are  designated  as  devices  /wl  -  /w7.  1)u 
open  a  device  window  as  you  do  any  other  OS-9  device.  You  tell 
OS-9  the  window's  parameters — including  whether  the  window  is 
fiff  text  or  grajdiics.  If  you  want  to  run  a  process  in  the  window, 
you  can  start  an  execution  environment,  such  as  a  shell,  on  the 
window.  (See  "Opening  a  Device  Window,"  later  in  this  chapter, 
and  the  DWSet  command  in  Chapt^  3.) 

Note:  If  you  want  only  to  send  output  to  the  device  win- 
dow— ^without  running  a  process  in  the  window — do  not 
start  a  shell  on  the  window. 

Device  windows  cannot  overlay  each  othw,  and  their  boundaries 
cannot  overlap. 


OS-9  Windowing  System 


Overlay  Windows 

An  overlay  window  is  a  window  that  you  open  on  top  of  a  device 
window.  (You  can  place  overlay  windows  omx  o^tm  overlay  win- 
dows, but  there  must  always  be  a  device  window  at  the  bottom  of 
the  stack.)  The  purpose  of  overlay  windows  is  to  display  com- 
puter dialog.  You  cannot  fork  a  shell  to  an  overlay  window;  how- 
ever, you  can  run  a  shdl  in  an  overlay  window.  Overlay  windows 
assume  the  screen  type  of  the  device  windows  they  overl£Qr. 

Opening  a  Device  Window 

To  open  a  device  window,  follow  these  steps: 

1.  If  you  want  to  allocate  memory  for  the  window,  use  OS-9's 
iniz  command.  Type: 

Ini  z  /V number  |  ENTER  I 

where  number  is  the  number  of  the  device  window  you  wish 
to  open  (1-7).  If  you  do  not  specify  number,  OS-9  uses  the 
next  available  4is^im  wim^xHr  aunber, 

]f  ym  db  not  use  the  ^olz  CixnuEftQi,  mmosey  is  allocated 
%minically  (as  needed)  to  the  wteift*^. 

2.  Next,  you  send  an  escape  sequence  to  OS-9  that  tells  it  the 
window's  parameters.  These  parameters  include  the  screen 
type,  size,  and  colors.  Ear  sample: 

wcreete  /w  -s'Z  20  10  40  10  01   00  00  I  ENTER  I 

or 

display  lb  20  02  14  0a  28  0a  01   00  00  /w 

I  ENTER  I 

sends  the  escape  sequence  for  the  next  available  window  to 
the  l3V<iiSet  cfnnmand.  Hhe  wca^te  command  lets  ym  use 
decimal  numbers,  while  the  display  command  requires 

hexadecimal  numbers. 
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If  you  wish  to  send  an  escape  sequence  to  a  specific  win- 
dow, route  the  command  to  that  device.  Ibr  example: 

wcpeate  /w2  -a-S  20  1  0  40  10  01   00  0 0  I  ENTER  | 

sends  the  escape  sequence  to  device  /w2.  The  functions  of 
the  codes,  as  used  in  the  wcreate  command,  are  as  follows: 

2  sets  a  screen  type  of  80  x  24  (text  only). 

20  starts  the  window  at  character/colvmin  20. 

10  starts  the  window  at  line/row  10. 

40  sets  a  window  size  of  40  characters. 

10  sets  a  window  size  of  10  lines. 

01  sets  the  foreground  color  to  blue. 

00  sets  the  background  color  to  white. 

GO  sets  the  border  to  white, 

1^  ym  do  not  sactd  escape  sequences^  OS-9  uses  de&ult 
descriptors  for  the  windows.  The  defo.ults  are: 

Size 

Window      Screen  Type     Starting  Position  (columns, 


Number       (chars.Aine)         (horiz.,  vert.)  rows) 


1  40  (text)                    0,0  27,11 

2  40  (text)  28,0  12,11 

3  40(tra*)                   0,12  40,12 

4  80  (text)                   0,0  60,11 

5  80  (text)  60,0  19,11 

6  80  (text)  80,0  80,12 

7  80(teart)                  0,0  80,24 


3.     Use  OS-9's  shell  command  to  fork  a  shell  to  the  window. 

Type: 

shell    i  =  /wnumber   S,  |  ENTER  | 

where  number  is  the  number  used  in  the  iniz  or  wcreate 
command.  The  i=  parameter  creates  an  immortal  shell. 
Creating  an  immortal  shell  protects  the  window  and  its 
shell  from  being  destroyed  if  you  accidentally  exit  the  shell 

using  I  CTRL  II  BREAK  |.  If  you  omit  the  i=  parameter,  the  shell 
is  forked  to  the  next  available  device  window. 

You  now  have  a  window  that  can  run  its  own  tasks.  Information 
displayed  in  that  window  is  automatically  scaled  to  the  window's 
size. 


1-3 


OS-9  Windowing  System 


Openly  nil  0¥@rlay  Window 

To  open  an  overlay  window,  use  the  Overlay  Window  Set  func- 
tion. (See  OWSet  in  Chapter  3,  "General  Commands.") 
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Overview  of  Commands  and 
Parameters 


The  windowing  commands  are  divided  among  three  chapters, 

based  on  their  functions. 

Chapter  3  describes  the  general  commands.  These  commands  let 
you  create  windows  and  buffers,  access  buffers,  set  switches,  and 
maintain  the  window  environment. 

Chapter  4  describes  the  drawing  commands.  Besides  letting  you 
draw  all  kinds  of  images  (circles,  ellipses,  arcs,  and  boxes,  to 
name  a  few),  these  commands  also  enable  you  to  color  areas  or  to 

fill  them  with  patterns. 

Chapter  5  describes  the  text  commands.  Use  these  commands  to 
manipalate  the  text  cttrsor  and  the  tiest  attributes.  Text  com- 
mands operate  on  hardware  text  screens  (Screen  Types  1  and  2) 

and  graphics  windows  if  a  font  is  selected. 

Each  command  description  lists  the  command's  name,  code,  and 
parameters.  To  call  a  Windowing  System  command  using  OS-9's 
display  command,  type  di  spley,  followed  by  the  command  code 
atiia  thi  wine®  |TO  vmtA  to  supply  for  the  pafaitte'ters. 


The  following  is  a  complete  list  of  the  parameter  abbreviations 
used  in  Chapters  3,  4,  and  5.  All  parameters  represent  a  single 
byte  of  information. 


Parameters 


Parameter 


Description 


HBX 
LBX 
HBY 
LBX 


high  order  byte  of  x  valve 
low  order  byte  of  x  value 
high  order  byte  ofy  vabie 
low  order  byte  ofy  value 


HBXo 
LBXo 
HBYo 
LBYo 


high  order  byte  ofx-offset  value  (relative) 
low  order  byte  ofx-offset  value  (relative) 
high  order  byte  of  y -offset  value  (relative) 
low  order  byte  of  y -offset  value  (relative) 


HBR 
LBR 


high  order  byte  of  radius 
low  order  byte  of  radius 
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Parameter 

Description 

HBL 

high  order  byte  of  length 

T.RT, 

iajw  ui  ijjiii  uyiti  Of  uciiQin 

HSX 

high  order  byte  of  size  in  x  direction 

ixjw  oraer  oyte  0/  size  m  x  u^ireciion 

TTQV 
XlDi 

high  order  byte  of  size  in  y  direction 

T  C!V 

tou/  order  oyie  oj  size  iri  y  ciireciioTi 

HBRx 

high  order  byte  of  radius  in  x  direction 

LBRx 

low  order  byte  of  radius  in  x  directum, 

GRP 

GET/PUT  buffer  group  number  (1-254) 

BFN 

GET/PUT  buffer  number  (1-255) 

LCN 

logic  code  number 

PRN 

palette  register  number  (0-15,  wraps  mod  15) 

CTN 

color  table  number  (0-63,  wraps  mod  64) 

FNM 

font  nutnber 

GPX 

character  position  x  (0-xmax) 

CPY 

character  position  y  (O-j'max) 

STY 

screen  type 

SVS 

save  switch  (0  =  nosave,  1  =  save  area 

under 

overlay) 

szx 

size  in  X  ( columns) 

SZY 

size  in  y  ( rows) 

XDR 

dimension  ratio  x  used  with  YDR  as 

YDR/ 

XDR 

YDR 

dimension  ratio  y 

BSW 

binmy  smitek  (0 = off,  1 = on) 
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General  Commands 


The  general  commands  let  you  set  up  and  customize  windows. 
They  also  let  you  set  up  and  access  image  buffers  and  select 
cobrs  fijr  the  screen. 
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BColor  Background  Color 

Function:  Lets  you  choose  a  color  palette  register  to  use  as  the 
background  color.  See  the  Palette  command  for  setting  up  the 
actual  colors. 

Code:  IB  33 

Parameters:  PRN 
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BoldSw  Bold  Switch 


FitneMon:  Enables  or  disables  boldfacing  for  text  on  graphics 
screens.  If  boldface  is  on,  the  screen  displays  subsequent  char- 
acters in  bold.  If  boldface  is  off,  the  screen  displays  subsequent 
character  in  the  regular  font. 

Code:  IB  3D 

Parameters:  BSW 

BSW  =  switch 

00  =  off(Defeult) 

01  =  on 

Notes: 

•  You  can  use  BoldSw  with  any  font. 

•  Boldface  is  not  supported  on  hardware  text  screens  (Screen 
Types  1  and  2). 
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Border  Border  Color 

Fttitetkitt:  L@es  you  dtes@"  the  .psli^  v^iir        &r  'th» 


screen  border.  See  the  Palette  coomiaiui  for  settiag  up  the 

actual  colors. 


Parameters:  PRN 
Notes: 

•  You  set  the  border  by  selecting  a  palette  register  to  use  for 
the  border  register.  When  the  actual  color  is  changed  in  the 
palette  register  selected  by  the  command,  the  color  of  the 
screen  border  changes  to  the  new  color.  In  general,  the  bor- 
der register  usually  matches  the  backgr^uad  palette 
register. 


Code: 


IB  34 
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CWArea  Change  Working  Area 

Function:  Lets  you  alter  the  working  area  of  the  window.  Nor- 
mally, the  system  uses  this  call  for  high-level  windowing,  but 
you  can  use  it  to  restrict  output  to  a  smalls  area  of  the  win- 
dow. 

Code:  IB  25 

Parameters:  CPX  CPY  SZX  SZY 
Notes: 

•  You  cannot  change  a  window's  working  area  to  be  larger 
than  the  predefined  area  of  the  window  as  set  by  DWSet  or 
OWSet. 

•  All  drawing  and  window  updating  commands  are  done 
the  current  tmrking  area  of  a  window.  The  working  icri^ 
de&ults  to  the  entire  size  of  the  window.  Scaling,  when  in 
use,  is  also  performed  relative  to  the  current  working  area 
of  a  window.  The  CW^rea  command  allows  users  to  restrict 
the  working  area  of  a  window  to  smaller  than  the  full  win- 
dow size.  Functions  which  might  be  done  by  opening  a  non- 
saved  overlay  window  to  draw  or  clear  an  image  and  then 
closing  the  overlay  can  be  accomplished  by  using  this  com- 
mand to  shorten  execution  time  where  an  actual  overlay 
window  is  not  needed. 
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DefColr  Defoult  Color 


Function:  Sets  the  palette  registers  back  to  their  default  val- 
ues. The  actual  values  of  the  palette  registers  depend  on  the 
type  of  monitor  you  are  using.  (See  montype  in  OS-9  Leod 
Two  Commands.) 

Code:  IB  30 

Parameters:  None 

Notes: 

•  The  default  color  definitions  apply  only  to  high-resolutum 

graphics  and  text  displays. 

•  The  system  sets  the  palette  registers  to  a  proper  compati- 
bility mode  when  switching  to  srareens  using  the  olto  VDG 
emulatbn  modes.  See  the  table  below: 


Window  System 
Color  Modes 

VDG-Compatibte  iladbs 

Color 

P#  Cotor 

P#  (Mm 

00  &  08 

White 

00  Green 

08  Black 

01  &  09 

Blue 

01  %Uow 

09  Green 

02  &  10 

Black 

02  Blue 

OA  Black 

03  &  11 

Green 

03  Red 

OB  Buff 

04&  12 

Red 

04  Buff 

OC  Black 

05&13 

Yellow 

05  Cyan 

OD  Green 

06  &  14 

Magenta 

06  Magenta 

OE  Black 

07  &  15 

Cyan 

07  Orange 

OF  Orange 

•  The  SetStat  call  lets  you  change  the  default  color  palette 
definition  when  using  the  windowing  system.  Default  colors 
in  the  VDG-Compatible  Mode  caonot  be  changed.  See  the 
&B-9  Imd  Ttm  mekrt&mi  Befiamm  manual  tniinibaticm 
on  SetStat. 

•  The  system's  defeult  colors  are  used  whenever  you  create  a 
new  window. 
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DfnGPBuf  Define  GET/PUT  Buffer 


Function:  Lets  you  define  the  size  of  the  GET/PUT  buffers  for 
the  system.  Once  you  allocate  a  GET/PUT  buffer,  it  remains 
allocated  until  you  use  the  EalBuf  command  to  delete  it. 

08-9  allocates  memory  for  GET/PUT  buffers  in  8K  blocks  that 
are  then  divided  into  the  different  GET/PUT  buffers.  Buffers 
are  divided  into  buffer  groups.  Therefore,  all  commands  deal- 
ing with  GET/PUT  buffers  must  specify  both  a  group  number 
and  a  buffer  number  within  that  group. 

Code:  IB  29 

Parameters:  GRP  BPN  HBL  LBL 

Hechnical: 


Hie  buffer  usage  map  is  as  follows: 


Group 

Buffer 

Number 

Number' 

Use 

0 

1  -  255 

Internal  use  only  (returns  errors) 

1  -  199 

1  -  255 

General  use  by  applications^ 

200  -  254 

1  -  255 

Reserved  (Microware  use  only)^ 

255 

1-255 

Intettial  use  mfy  (rekiras  emsrs) 

'  Buffer  Number  0  is  invalid  and  cannot  be  used. 

^  The  application  program  should  request  its  user  ID  via 

the  GetID  system  call  to  use  as  its  group  number  finr 

btxf^  altocation. 
^  The  standard  group  numbers  are  defined  as  fellows: 

Note:  The  names,  buffer  groups,  and  buffer  numbers  are 
defined  in  the  assembly  definition  file.  The  decimal  num- 
ber you  use  to  call  these  are  in  parentheses  next  to  the 
name.  For  example,  to  select  the  Arrow  pointer, 
GiD—Ptr  and  I*tr_^rr,  you  use  202,1  as  the  group/buffer 
number. 
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Grp_Fnt(200)  =  font  group  for  system  fonts 

Plit_S8x8(l)  =  standard  8x8  font 

Fnt_S6x8(2)  =  standard  6x8  font 
Fnt_G8x8(3)  =  standard  graphics  font 

The  standard  fonts  are  in  the  file  SYS/ 
Stdfbnts. 

Grp_Clip(201)  =  clipboarding  group  (for  Multiview) 

Grp_PtrC202)  =  graphics  cursor  (pointer)  group 

Ptr  Arr(l)     =  arrow  pointer  (hp  =  0,0) 

Ptr_Pen(2)  =  pencil  pointer  (hp  =  0,0) 
Ptr_LCH(3)   =  large  cross  hair  pointer 

(hp  =  7,7) 

Ptr_Slp(4)      =  sleep  indicator  (hourglass) 
Ptr__Ill(5)       =  illegal  indicator 
Ptr_Txt(6)     =  text  pointer  (hp  =  3,3) 
Pfcr_SCH(7)   =  small  cross  hair  pointer 

(hp  =  3,3) 


hp 


=  hit  point,  the  coordinates 
of  the  actual  pdnt  m  $m 
object  at  which  the  cursor 
should  be  centered. 


Grp_Pat2(203) 
Grp_Pat4(204) 
Grp_P&t6(205) 


The  standard  pointers  are  in  the  file  SYS/ 
StdPtrs. 

=  two  color  patterns 
=  four  color  patterns 
=  sixteen  color  patterns 


Pat_Dot(l) 

Pat_Vrt(2) 

Pat_Hrz(3) 

Pat^_XHtc(4) 

Pat_LSnt(5) 

Pat_RSnt(6) 

Pat^SDot(7) 

PatJ3Dot(8) 


=  dot  pattern 
=  vertical  line  pattern 
=  horizontal  line  pattern 
=  q:os^  hatch  pattmi 
=  left  slanted  lines 
=  right  slanted  lines 
=  small  dot  pattern 
=  large  dot  pattmi 


Each  pattern  is  found  within  each  of  the 
pattern  groups. 

Standard  patterns  are  in  the  files 
SYS/StdPats_16. 
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All  files  have  GPLoad  commaais  imb@dd@d  in  file,  along  with 
ihe  data..  To  load  fonts,  pointef%  m  patterns,  simply  merge  them 
to  any  window  device;  Imc  exaa$lc»: 

merge  Si?i/StdFoTit  s  |  ENTER  | 

sends  the  standard  font  to  standard  output  which  ma^  be  fedi- 
rected  to  another  device  if  the  current  output  device  is  not  a  win- 
dow device  (such  as  when  term  is  a  VDG  screen). 

You  only  need  to  load  fonts  once  for  the  entire  system.  Once  a 
Get/Put  buffer  is  loaded,  it  is  available  to  all  devices  and  pro- 
cesses in  the  system. 
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DWEnd  Device  Window  End 


Function:  Ends  a  current  device  window.  DWEnd  closes  til© 
display  window.  K  the  window  was  the  last  device  window  on 
the  screen,  DWEnd  also  deallocates  the  memory  used  by  the 
window.  If  the  window  is  an  interactive  window,  OS-9  auto- 
matically switches  you  to  a  new  device  window,  if  one  is 
available. 

Code:  IB  24 

Parameters:  None 

Notes: 

•  DWEnd  is  only  needed  for  windows  that  have  been  attached 
via  the  iniz  utility  or  the  I$Attach  system  call.  Non- 
attached  windows  have  an  implied  DWEnd  conmiand  that  is 
^eeuted  yshm  ym  dose  the  pat&. 
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DWProtSw  Device  Window  Protect  Switch 

Function:  Disables  and  enables  device  window  protection.  By 
default,  device  windows  are  protected  so  that  you  cannot  over- 
lay than  with  other  device  windows.  This  type  <rf  protection 
helps  avoid  the  possibility  of  destroying  the  contents  a£  either 

or  both  windows. 

Code:  IB  36 

Parameters:  BSW 

BSW  =  switch 

00  =  oEf 

01  =  on  (Defeult) 

Notes: 

•  We  recommend  that  you  not  turn  off  device  window  protec- 
tion. If  you  do,  however,  use  extreme  discretion  because  you 
might  destr^  the  contents  of  the  windows.  OS-9  does  not 
return  an  error  if  you  request  that  a  new  window  be  placed 
over  an  area  of  the  screen  which  is  already  in  use  by  an 
unprotected  window. 
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Device  Wintiow  Set 


Ftmction:  Lets  you  define  a  window's  size  and  location  on  the 
physical  screen.  Use  DWSet  after  opening  a  path  to  a  device 
window. 

Code:  IB  20 

Parameters:  STY  CPX  CPY  SZX  SZY  PRNl  PRN2  PRN3 

PRNl  =  Foreground 
PRN2  =  Background 
PRN3  =  Border  (if  STY  ^  1) 

Notes: 

•  The  iniz  and  display  commands  open  paths  to  the  device 

window. 

•  When  using  DWSet  in  a  program,  you  must  first  open  the 
device. 

•  Output  to  a  new  window  is  ignored  until  OS-9  receives  a 
DWSet  command,  unless  de&ults  are  present  in  tiie  device 
descriptor  (/wl-/w7).  W  deftcalts  em  i»sieat  in  the  de^dee 
descriptors,  OS-9  automatically  executes  DWSet,  using 

those  defaults. 

•  When  OS-9  receives  the  DWSet,  it  allocates  memory  for  the 
window,  and  clears  the  window  to  the  current  badtground 
color.  If  the  standard  font  is  already  in  memory,  OS-9 
assigns  it  as  the  default  font.  If  the  standard  font  is  not  in 

memory,  you  must  execute  a  font  set  (Font)  command  after 
loading  the  fonts  to  produce  text  output  on  a  graphics 
window. 

•  Use  the  Screen  Type  code  (STY)  to  define  the  resolution 
and  color  mode  of  the  new  screen.  If  the  screen  tiype  code  is 
zero,  OS-9  opens  the  window  on  the  process's  currently 
selected  screen.  If  the  code  is  01,  OS-9  opens  the  window  on 
the  currently  displayed  screen.  If  the  code  is  non-zero,  OS-9 
allocates  a  new  screen  for  the  window.  The  following 
describes  the  acceptable  screen  types: 
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Code  Scgeen  Slase       Colors        Memory  Type 


FF 

Current  Displayed  Screen^ 

00 

Process's  Current  Screen 

01 

40  X  24 

8  &  8 

2000 

Text 

02 

80  x24 

8  &  8 

4000 

Text 

05 

640  X  192 

2 

16000 

Graphics 

06 

320  X  192 

4 

16000 

Graphics 

07 

640  X  192 

4 

32000 

Graphics 

08 

320  X  192 

16 

32000 

Graphics 

^  Use  the  Current  Displayed  Screen 

option  only  in  proce- 

dure  files  to  display  several  windows  on  the  same  physical 
screen.  All  programs  should  operate  on  that  process's  cur- 
rent screen. 

•  The  location  of  the  window  on  the  physical  screen  is  deta:- 
mined  by  the  diagonal  line  defined  by: 

(CPX,CPY)  and  (CPX  +  SZX,  CPY  +  SZY) 

•  The  foreground,  background,  and  border  register  numbers 
CPRM,  HRN2,  and  PRN8)  define  the  palette  tegisters  vmi 
for  the  foreground  and  background  coli^«  See  the  Palette 
command  in  this  chapter  for  more  information. 

•  When  an  implicit  or  explicit  DWSet  command  is  done  on  a 
window,  the  window  automatically  clears  to  the  background 
color. 

•  All  windows  on  the  screen  must  be  of  the  same  type  (either 
text  or  graphics). 

•  %Ittes  in  the  palette  register  affect  all  windows  m  ^cm 
screen.  However,  you  can  choose  which  register  to  US©  fer 
foreground  and  background  for  each  window.  That  is,  OS-9 
maintains  palette  registers  and  border  register  numbers  for 
the  entire  screen  and  foreground  and  background  register 
nttDsb^s  fyt  each  individual  wiluiow. 

•  OS-9  deaUocates  memory  &r  a  screm  when  you  terminate 
the  last  window  m  that  screen. 
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Function:  Lets  you  select  a  color  palette  register  for  the  fore- 
graand  color.  See  the  Palette  command  for  settirig  the  actual 
colors. 

Code:  IB  32 

Parameters:  PRN 
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Font  Select  Bbnt 


Function:  Lets  you  select/change  the  current  font.  Before  you 
can  use  this  command,  the  font  must  be  loaded  into  the  speci- 
fied GET/PUT  group  and  buffer  (using  GPLoad).  See  the 
GPLoad  command  for  information  on  loading  font  buffers. 

Code:  IB  3A 

Parameters:  GRP  BFN 

Notes: 

•  You  can  select  proportional  spacing  for  the  font  by  usii^ 
PropSw. 

•  All  font  data  is  a  2-color  bit  map  of  the  font. 

•  Each  character  in  the  font  data  consists  of  8  bytes  of  data. 
The  first  byte  defines  the  top  scan  line,  the  second  byte 
defines  the  second  scan  line,  and  so  on.  The  high-order  bit 
of  each  byte  defines  the  first  pixel  of  the  scan  line,  the  next 
bit  defines  the  next  pixel,  and  so  on.  For  acample,  the  letter 
"A"  would  be  represented  like  this: 

Byte    Pixel  Representation 


10 

•       •       •              •       •  • 

28 

•       •              •      ^   «  ■ 

44 
44 

•      •  •  •  ^  • 

7c 

.  #####. 

44 

•      •  •  •  ■ 

44 

.#...#. 

00 

Note  that  6x8  fonts  ignore  the  last  2  bits  per  byte. 

•  The  fonts  are  ordered  with  characters  in  the  following 
ranges: 

$00-$  IP      International  dbaasctsrs  Isee  mapping  below) 
$20-$7F       Standard  ASCII  characters 
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International  characters  or  any  characters  in  the  font  below 
character  $20  (hex)  are  printed  according  to  the  following 
table: 

Character  position     Charl        or  Ghar2 


1  n  TTiTrf 

ill  lUilL 

$00 

$C1 

$E1 

$01 

iCf 

$E2 

$02 

$C3 

$E3 

$03 

$C4 

$E4 

$04 

$C5 

$E5 

$05 

$C6 

$E6 

$06 

$C7 

$E7 

$07 

$C8 

$E8 

$08 

$C9 

$E9 

$09 

$CA 

$EA 

$0A 

$CB 

$EB 

$0B 

$CC 

$EC 

$0C 

$CD 

$ED 

$0D 

$CE 

$EE 

$0E 

$CP 

$EF 

$0F 

$D0 

$F0 

$10 

$D1 

$F1 

$11 

$D2 

$F2 

$12 

$D3 

$F3 

#18 

$D4 

|f4 

$14 

$D5 

$F5 

$15 

$D6 

$F6 

$16 

$D7 

$F7 

$17 

$D8 

$F8 

$18 

fl>9 

$F9 

$19 

$DA 

$FA 

$1A 

$AA 

$BA 

$1B 

$AB 

$BB 

$ic 

$AC 

$BC 

$1D 

$AD 

$BD 

$1E 

$AE 

$BE 

$1F 

$AF 

$BF 
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GCSet  Graphics  Cursor  Set 

FiofiteMon:  Creates  a  GET/PUT  buffer  for  defining  the  graphics 
cursor  that  the  system  displays.  You  must  use  GCSet  to  dis- 
play a  graphic  cursor. 

Code:  IB  39 

Parameters:  GRP  BFN 

Notes: 

•  To  turn  off  the  graphics  cursor  specify  GRP  as  00. 

•  A  system  standard  buffer  or  a  user-defined  buffer  can  be 
used  for  the  graphics  cursor. 
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GetBlk  Get  Block 


Function:  Saves  an  area  of  tlie  screen  to  a  GET/PUT  bviffer. 
Once  the  block  is  saved,  yau  can  put  it  back  in  its  origijial 
location  or  In  another  on  the  scifeen,  using  the  PutBlk 
command. 

Code:  IB  20 

Parameters:  GRP  BFN  HBX  LBX  HBY  LBY  HSX  LSX  HSY 

LSY 


•  The  GET/PUT  buffer  maintains  information  on  the  size  of 
the  hhck  stored  in  the  hxAt  so  ^t  the  PutBlk  comBuaDd 
works  nunre  amimiatically. 

•  If  the  GET/PUT  buffer  is  not  already  defined,  GetBlk  cre- 
ates it.  If  the  buffer  is  defined,  the  data  must  be  equal  to  or 
smaller  than  the  original  size  of  the  buffer. 


HBX/LBX 
HBY/LBX 

HSX/LSX 
HSY/LSY 


x-location  of  block  (upper  left  comer) 
y -location  of  block 

x-dimension  of  block 
y -dimension  of  block 


Notes: 


3-18 


General  Commands  1 3 


GPLoad  GET/PUT  Buffer  Load 


Function:  Preloads  GET/PUT  fenitet  wi&  io^s  tlmA  you 
em.  jmm  to  tibe  m^imx  later,  tislog  PmlMk. 

If  tlie  GET/PUT  bufife-  is  not  alreacfy  created,  GPLoad  creates 
it. 

If  the  buffer  was  previously  created,  the  size  of  the  passed 
data  must  be  equal  to  or  smaller  than  the  original  size  of  the 
buffer.  Otherwise,  GPLoad  truncates  the  data  to  the  size  of 
the  buffer. 

Code:  IB  2B 

Parameters:  GRP  BFN  STY  HSX  LSX  HSY  LSY  HBL  LBL 
(Data...) 

STY  =  format 

HSX/LSX  =  x-dimension  of  stored  block 
HSY/LSY  =  y -dimension  of  stored  block 
HBL/LBL  =  number  of  bytes  in  data 

Notes: 

•  Buffers  are  maintained  in  a  linked  list  system. 

•  Buffers  to  be  used  most  should  be  allocated  last  to  mini- 
mize the  search  time  in  finding  the  buffers. 

•  When  loading  a  Font  GET/PUT  Buffer,  the  parameters  are 
m  Allows: 

GEP  BFN  STY  HSX  LSX  HSY  LSY  HBL  LBL 
(Data...) 

GRP  =  254 

STY  =  5 

HSX/LSX  =  x-dimension  size  of  Font  6  or  8 
HSY/LSY  =  y-'dimension  size  of  Font  8 
EDBL/LML  =  sim  of  font  data  (not  including  this 
header  in&rmaMcm) 

See  the  Ibnt  command  for  more  information  on  font  data. 
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KilBuf  KiU  GET/PUT  Buffer 


Function:  Deallocates  the  buffer  specified  bf  the  group  and 
buffer  number.  To  deallocate  the  entire  group  of  buffers,  set 
the  buffer  number  to  0. 

Code:  IB  2A 

Parameters:  GRP  BFN 

Notes: 

•  KilBuf  returns  memory  used  by  the  buffer  to  a  free  list. 
When  an  entire  block  of  memory  has  been  put  on  the  free 
list,  the  block  is  returned  to  the  system. 
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LSet  Logic  Set 


Function:  Lets  you  create  special  effects  by  specifying  the 
type  of  logic  used  when  storing  data,  which  represents  an 
image,  to  memory.  The  specified  logic  code  is  used  by  all  draw 
commands  imtil  you  either  choose  a  new  logic  or  turn  off  the 
(^^atei.  lb  turn  off  the  logic  function,  set  the  logic  code 
to  00. 


LCN  =  logic  code  number 

GO  =  No  logic  code;  store  new  data  on 
screen 

01  =  AND  new  data  with  data  on 

screen 

02  =  OR  new  data  with  data  on  screen 

03  -  XOR  new  data  with  data  on  screen 


•  The  following  tables  summarize  logic  operations  in  bit 

manipulations: 


Code: 


IB  2F 


Parameters:  LCN 


Notes: 


AND 


First 
Operand 


Second 
Operand 


Result 


1 
1 
0 
0 


1 
0 

1 

0 


1 

0 
0 

0 


OR 


First 
Operand 


Second 
Operand 


Result 


1 
1 
0 
0 


1 
0 
1 
0 


1 
1 
1 

0 
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XOR 


First 
Operand 


Second 
Operand 


Result 


1 
1 
0 
0 


1 
0 
1 
0 


0 
1 
1 
0 


•  Data  items  are  represented  as  palette  register  numbers  in 
memory.  Since  logic  is  performed  on  the  palette  register 
number  and  not  the  colors  in  the  registers,  you  should 
choose  colors  for  palette  registers  carefully  so  that  you 
obtain  the  desired  results.  You  may  want  to  choose  the 
eolors  tor  the  palette  registers  so  that  LSet  appears  to  and, 
or,  and  xor  the  colors  rather  than  the  register  numbers.  Ebr 
example: 

Palette  #  Color  Alternative  Order 


0 
1 
2 
3 


White 
Blue 
Black 
Green 


Black 
Blue 
Green 
White 
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OWEnd  Overlay  Window  End 


Funciloni  Ends  a  current  evKrlay  window.  OWEnd  closis  the 
overlay  window  and  deallocates  memory  used  by  the  window. 
If  you  opened  the  window  with  a  save  switch  value  of  hexadec- 
imal 01,  OS-9  restores  the  area  under  the  window.  If  you  did 
not,  OS-9  does  not  restore  the  area  and  any  fucthrar  output  is 
sent  to  the  tmA  lower  overlay  window  or  io  the  iifiee  window, 
if  no  overlay  window  exists. 

Code:  IB  23 

Parameters:  None 
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OWSet  Overlay  Window  Set 

PtmelAoHS  Use  OWSet  to  create  an  owrlay  window  on  an  exist- 
ing device  window.  OS-9  reconfigures  current  device  window 
paths  to  use  a  new  area  of  the  screen  as  the  current  logical 
device  window. 

Code:  IB  22 

Pttranw^s:  SVS  CPX  CPY  SZX  SZY  Ml  PRN2 

SVS  =  Slave  switch 

00  =  Do  not  save  area  overlayed 

01  =  Save  area  overlayed  and  restore  at 

close 

PRNl  =  background  palette  register 
PRN2  =  foreground  palette  register 

Notes: 

•  If  you  set  SVS  to  zero,  any  writes  to  the  new  overlay  win- 
dow destroy  the  area  under  the  window.  You  might  want  to 
set  SVS  to  zero  if  your  system  is  already  using  most  of  its 
available  maaftory.  You  might  also  set  SVS  to  z&co  whenever 
it  takes  relatively  little  time  to  redraw  the  area  under  the 
overlay  window  once  it  is  closed. 

•  If  you  have  ample  memory,  specify  SVS  as  1.  Doing  this 
causes  the  system  to  save  the  area  under  the  new  overlay 
window.  The  system  restores  the  area  when  you  terminate 
the  mw  mrnl^  wjMidw.  (See  QWBai*) 

•  The  size  of  tiie  overlay  window  is  specWed  in  standard 
characters.  Use  the  same  resolution  (number  of  characters) 
as  the  device  window  that  will  reside  beneath  the  overlay 
window.  Have  your  program  determine  the  original  size  of 
the  device  window  at  startup  (using  the  SS.ScSiz  GETSTAT 
feall),  if  the  device  window  does  not  cover  the  entire  mtma. 
See  the  OS-9  Level  Two  Technical  Reference  manual  fijr 
information  on  the  SS.ScSiz  GETSTAT  call. 
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•  Overlay  windows  can  be  created  on  top  of  other  overlay 
windows;  however,  you  can  only  write  to  the  top  most  win- 
dow. Overlay  windows  are  "stacked"  on  top  of  each  oth^ 
logically.  To  get  back  down  to  a  given  overlay,  you  must 
close  (OWEnd)  any  overlay  windows  that  reside  on  top  of 
the  desired  overlay  window. 

•  Stacked  overlay  windows  do  not  need  to  reside  directly  on 
top  of  underlying  overlay  windows.  However,  all  overlay 
windows  must  reside  within  the  boundaries  of  the  iinder^- 
ing  device  window. 
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Palette  Cliaiiie  l^tte 


Function:  Lets  you  change  the  color  associated  with  each  of 

the  16  palette  registers. 

Code:  IB  31 

Parameters:  PEN  CTN 
Notes: 

•  Changing  a  palette  register  value  causes  all  areas  of  the 
screen  using  that  palette  register  to  change  to  the  new 
color.  In  addition,  if  the  border  is  set  to  that  palette  regis- 
ter, the  border  cdor  also  changes.  See  the  Border  coinmand 
i>r  mm%  inJtaMatitm. 

•  Coloi*  are  made  up  by  setting  the  red,  green,  and  blue  bits 
in  the  color  byte  which  is  inserted  in  the  palette  register. 
The  bits  are  laid  out  as  follows: 


Bit 

Color 

0 

Blue  low 

1 

Green  low 

2 

Red  low 

3 

Blue  high 

4 

Green  high 

5 

Red  high 

6 

unused 

7 

unused 

By  using  six  bits  for  color  (2  each  for  red,  green  and  blue) 
there  is  a  possibility  of  64  from  wiiich  to  choose.  Some  of 
the  colors  are  defined  as  shown: 


White 
Black 

Standard  Blue 
Standard  Green 
Standard  Red 


00111111  =  $3F  (all  color  bits  set) 

00000000  =  $00  (no  color  bits  set) 

00001001  =  $09  (both  blue  bits  set) 

00010010  =  $12  (both  green  bits  set) 

00100100  =  $24  (both  red  bits  set) 
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Note:  Tliese  colors  are  for  RGB  monitors.  The  composite 
monitors  use  a  different  color  coding  and  do  not  directly 
match  pure  RGB  colors.  To  get  composite  color  from  the 
RGB  colors,  the  system  uses  conversion  tables.  The  colors 
were  assigned  to  match  the  RGB  colors  as  close  as  possible. 
There  are,  however,  a  widea:  range  of  composite  colors,  so 
the  colors  without  direct  matches  were  assigned  to  the  clos- 
est possible  match.  The  white,  black,  standard  green,  and 
standard  orange  are  the  same  in  both  RGB  and  composite. 
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PropSw  Proportional  Switch 

Function:  Enables  and  disables  the  automatic  proportional 
spacing  of  characters.  Normally,  characters  are  not  proportion- 
ally spaced. 

Code:  IB  3F 

Parameters:  BSW 

BSW  =  switch 

m  « «ff(jtefeuit) 

01  =  on 

Notes: 

•  Any  standard  software  font  used  in  a  graphics  screen  can 

be  proportionally  spaced. 

•  Proportional  spacing  is  not  supported  on  hardware  text 
screens. 


3-28 


General  Commands  1 3 


PSet  Pattern  Set 


Function:  Selects  a  preloaded  GET/PUT  buffer  as  a  pattern 
RAM  array.  This  pattern  is  used  with  all  draw  commands 
until  ym  eithra:  change  the  pattern  or  turn  it  off  by  passii^  a 
parameter  of  00  as  GRP  (Group  Number). 

Code:  IB  2E 

Parameters:  GRP  BFN 

Notes: 

•  The  pattern  array  is  a  32  x  8  pixel  representation  of  graph- 
ics memory.  The  color  mode  defines  the  ztumber  of  bits  pesF 
pixel  and  pixels  per  bj^e.  So,  be  sure  to  tatoe  ft©  emnsaat 
color  mode  into  consideration  when  creating  a  pattern 

array. 

•  The  GET/PUT  buffer  can  be  of  any  size,  but  only  the  num- 
ber of  bytes  as  described  by  the  following  table  are  used: 

Color 

 Mode  Size  of  Pattern  Array  

2  4  bytes  x  8  =   32  bytes  (1  bit  per  pixel) 

4  8  hytes  x  8  =    64  bytes  (2  bits  per 

pixel) 

16  16  bytes  x  8  =  128  bytes  (4  bits  per 

pixel) 

•  The  buffer  must  contain  at  least  the  number  of  bytes 
required  by  the  current  color  mode.  If  the  buffer  is  larger 
than  required,  the  ^ra  hytea  are  ignored. 

•  To  turn  off  patterning,  set  GRP  to  00. 


3-29 


OS -9  Windowing  System 


•  The  following  example  creates  a  two  color  pattern  of  vertical 
lines.  A  two  color  pattern  is  made  up  of  I's  and  O's.  The 
diagram  below  shows  the  bit  set  pattern  (note  that  one 

pixel  is  equal  to  one  bit): 

lOlOlOlOlQlOlOlOlOlOlOlOlOlOlOlO 
10101010101010101010101010101010 

10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 
10101010101010101010101010101010 

When  the  binary  for  the  2x8  pixel  data  is  compressed  into 
byte  data,  notice  that  each  row  consists  of  4  bytes  of  data. 
The  pattern  now  boks  like  this: 

$55  $55  $55  $55 
$55  $55  $55  $55 
$55  $55  $55  $55 

$55  $55  $55  $55  $55  =  01010101 

$55  $55  $55  $55 
$55  $55  $55  $55 

$55  $55  $55  $55 
$55  $55  $55  $55 

To  load  the  pattern  in  the  system,  use  the  GPLoad  com- 
mand. To  load  this  particular  pattern  into  Group  2  and 
Buffer  1,  the  command  would  be: 

display  lb  2b  02  01  00  20  00  08  00   20  55  55  ...55  |  ENTER  | 


32  times 
number  of  bytes  (32) 
y  size  of  pattern  (8) 
X  size  of  pattern  (32) 
buffer  number 
group  number 
GPLoad  code 
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•  When  making  a  pattern  using  4  colors,  a  pixel  is  made  up 
of  two  bits  instead  of  one.  This  means  that  the  pattern  con- 
sists of  64  bytes  instead  of  32.  The  diagram  below  shows 
the  bit  set  pattern  for  the  sams  vertical  pattern  ixsing  4 
colors: 

iiooiiomiooiiooiiooiioonooiiomooiiooiiooiiooiiooiiooiiooiioD 

1100110011001100110011001100110011001100110011001100110011001100 
1100110011001100110011001100110011001100110011001100110011001100 
1100110011001100110011001100110011001100110011001100110011001100 
1100110011001100110011001100110011001100110011001100110011001100 
1100110011001100110011001100110011001100110011001100110011001100 
1100110011001100110011001100110011001100110011001100110011001100 
1100110011001100110011001100110011001100110011001100110011001100 

When  the  binary  for  the  4x8  pixel  data  is  compressed  into 
byte  data,  notice  that  each  row  consists  of  8  bytes  of  data. 
The  pattern  now  looks  like  this: 

ICC  $00  $00  $00  $00  $CC  $00  $00 

$CC  $00  $00  $00  $00  $00  $00  $00 

$00  $00  $00  $00  $00  $00  $00  $00 

$00  $00  $00  $00  $00  $00  $00  $00  $CC  =  1100 

$00  $00  $00  $00  $00  $00  $00  $CC 

$00  $00  $00  $00  $00  $00  $00  $00 

$00  $00  $00  $00  $00  $00  $00  $00 

$CC  ICC  ICC  ICC  ICC  ICC  ICC  ICC 

To  load  the  pattern  in  the  systeiM,,  'Bte  the  GPLoad  com- 
mand as  described  for  the  2  color  example  but  specify  $40 
(64)  bytes  instead  of  |20  (32). 

•  When  making  a  pattern  using  16  colors,  a  pixel  is  made  up 
of  four  bits  instead  of  one.  This  means  that  the  pattern  con- 
sists of  128  bytes.  Each  line  in  the  bit  pattern  would  look 
like  this: 

11110000...{repeat  pattern  for  16  total  sets}...11110000 

When  the  binary  for  the  8x8  pixel  data  is  compressed  into 
byte  data,  the  pattern  is  a  series  of  |F0. 

To  load  the  pattern  in  the  system,  use  the  GPLoad  com- 
mand and  specify  $80  (128)  bytes  as  the  size. 
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PutBlk  Put  Block 


Function:  Moves  a  GET/PUT  buffer,  previously  copied  from  the 
screen  or  loaded  with  GPLoad,  to  an  area  of  the  screen. 

Code:  IB  2D 

Parameters:  GRP  BFN  HEX  LBX  HBY  LBY 

HBX/UBX  —  x-location  of  block 
(upper  IdOt  comer) 
HBY/LBY  =  y-loceOionofiaock 

•  The  dimensions  of  the  block  were  saved  in  the  GET/PUT 
buffer  when  you  created  it.  OS-9  uses  these  dimensions 

•  The  wmmei  tyye  conv^ion  is  automatically  hmM&d.  1^  %6 
Fatfilk  rotiMiae  in  the  im^. 

•  GET/PUT  buffers  cannot  be  scaled.  The  image  will  be 
clipped  if  it  does  not  fit  within  the  window. 
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ScaleSw  Scale  Switch 

FuncMon:  Disables  and  enables  automatic  scaling.  Normally, 
automatic  scaling  is  enabled.  When  scaling  is  enabled,  coordi- 
nates refer  to  a  relative  location  in  a  window  that  is  propor- 
tionate to  the  size  of  the  window.  When  scaling  is  disabled, 
coordinates  passed  to  a  command  will  be  the  actual  coordi- 
nate for  that  t3^e  of  soreen  relative  to  the  eaigfia  of  the 
window. 

Code:  IB  35 

Parameters:  BSW 

BSW  =  switch 

00  =  off 

01  ^  on  CMtilt) 

Notes: 

•  A  useful  application  of  disabled  scaling  is  the  arrangement 
of  references  betwe^  a  figure  and  t^. 

•  All  coordinates  are  relative  to  the  wilidow's  origin  (0,0). 
The  valid  range  for  the  coordinates: 

Scaling  enabled: 

y  =  0-191 
X  =  0-639 

Scaling  iisahted: 

y  *^  0*8^  ofy  - 1 
X  =  0-size  ofx  - 1 
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Select  Window  Select 


Function:  Causes  the  cxurenl  pt^eess's  windsw  to  become  the 
active  (display)  window,  15)U  can  select  a  different  window  hy 

using  the  form: 

display   IB  21  >/wnLimber 

where  number  is  the  desired  window  number.  If  the  process 
that  executes  the  select  is  running  on  the  current  interactive 
(input/display)  window,  the  selected  window  becomes  the 
interactive  win^jfw,  md  the  oth^  window  becimes  pissive. 

Code:  IB  21 

Parameters:  None 

Notes: 

•  The  keyboard  is  attached  to  the  process's  selected  window 
through  the  use  of  the  |  clear  |  key.  This  lets  fm  tapit  data 
from  the  keyboard  to  different  windows  hy  using  the  ICLEABI 
key  to  select  the  window. 

•  All  display  windows  that  occupy  the  same  screen  are  also 
displayed. 

•  The  device  window  which  owns  the  keyboard  is  the  current 
interactive  window.  The  interactive  window  is  always  the 
window  being  displayed.  Only  one  process  may  receive 
input  from  the  keyboard  at  a  time.  Many  processes  may  be 
changing  the  output  information  on  their  own  windows; 
however,  you  can  only  see  the  information  that  is  displayed 
oa.  the  interactive  window  and  any  other  window  on  the 
same  screen  as  the  interactive  window. 
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TCharSw  Transparent  Character  Switch 

Function:  Defines  the  character  mode  to  be  used  when  putting 

characters  on  the  graphics  screens. 

In  the  default  mode  (transparent  off),  the  system  uses  block 
characters  that  draw  the  entire  foreground  and  background  for 

that  cell. 

When  in  transparent  mode,  the  oniy  pixels  that  are  changed 
are  the  ones  where  the  character  actually  has  pixels  set  in  its 
font.  When  transparent  mode  is  off,  all  pixels  in  the  character 
block  are  set:  foreground  or  font  pixels  in  the  foreground  color 
and  othws  in  the  background  color. 

Code:  IB  3C 

Parameters:  BSW 

BSW  =  switch 

00  =  off  (Default) 

01  =  on 
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Drawing  Commands 


All  drawing  commands  relate  to  an  invisible  point  of  reference 
on  the  screen  called  the  draw  pointer.  Originally,  the  draw 
pointer  is  at  position  0,0.  Ym  can  change  the  position  by  using 
the  SetDPtr  and  RSetDPtr  commands  described  in  this  chapter. 
In  addition,  some  draw  commands  automatically  update  the 
draw  pointer.  For  example,  the  LineM  command  draws  a  line 
from  the  current  draw  pointer  position  to  the  specified  end  coor- 
dinates and  moves  the  draw  pointer  to  those  end  eoordinates. 
The  Line  command  draws  a  line  but  does  not  move  the  pointer. 

AIsO;,  note  that  all  draw  commands  are  affected  hy  tiie  pattern 
and  logic  commands  described  in  Chapter  3. 

Do  not  confuse  the  draw  pointer  with  the  graphics  cursor.  The 
graphics  cursor  is  the  graphic  representation  of  the  mouse/joy- 
stick position  on  the  screen. 

In  this  chapter,  commands  that  use  relative  coordinates  {.offsets) 
are  listed  with  their  countei^aits  tiiat  use  alraolute  coordinates. 
Bbr  example,  RSetDPtr  is  listed  under  SetDPtr. 
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Draw  Arc 


Fuliction:  Draws  an  arc  with  its  ffiMf oint  at  the  current  draw 
pointer  position.  You  specify  the  curve  by  both  the  X  and  Y 
dimensions,  as  you  do  an  ellipse.  In  this  way,  you  can  draw 
either  elliptical  or  circular  arcs.  The  arc  is  clipped  by  a  line 
defined  by  the  (XOl.YOl)  -  (X02,Y02)  coordinates.  These  coor- 
dinates are  signed  16  bit  values  and  are  i%taMve>  to  fihe  c^ter 
of  the  ellipse.  The  draw  pointer  remains  in  its  original 
position. 

Code:  IB  52 


Parameters:  HBRx  LBRx  HBRy  LBRy  HXOl  LXOl  HYOl 

lyoi  mj§  mm  hyo2  iyo2 


•  The  resulting  arc  depends  on  the  ord^  in  which  you  specify 
the  line  coarc^nateB.  AreiP  first  6xm%  Ihe  line  femi  Point 
1  to  Point  2  and  then  draws  the  elli^e  in  a  clockwise 

direction. 

•  The  coordinates  of  the  screen  are  as  follows: 


Notes: 


-Y 


-X 


-1-X 


+  Y 
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Bar  Draw  Bar 

FlXOfsMom  Draws  and  fills  a  rectattgle  that  is  defined  by  the 
dil^^ial.  Ifae  from  the  current  draw  pointer  position  to  the 
specified  position.  The  box  is  drawn  in  the  current  foreground 
cobr.  The  draw  pointer  returns  to  its  original  location. 

Code:  IB  4A 

"Baxmmimm  HBX  LKK  HBY  LBY 

RBar  Relative  Draw  Bar 

Function:  Draws  asoA  fills  a  rectangle  that  is  dinned  by  the 
diagonal  line  from  the  current  draw  pointer  position  to  the 
point  specified  by  the  offsets.  The  box  is  drawn  in  the  current 
foreground  color.  The  draw  pointer  returns  to  its  original  loca- 
tion. This  is  a  relative  command. 

Code:  IB  4B 

I^ameters:  HBXo  LBXo  HB%  LBYo 
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Box  Draw  Box 


Function:  Draws  a  rectangle  that  is  defined  by  the  diagonal 
line  from  the  current  draw  pointer  position  to  the  specified 
position.  The  box  is  drawn  in  the  curr^it  foregroTjiid.  color. 
The  draw  pointer  returns  to  its  original  location. 

Code:  IB  48 

Parameters:  HBX  LBX  HBY  LEY 

RBox  Relative  Draw  Box 


Function:  Draws  a  rectangle  that  is  defined  by  the  diagonal 
line  from  the  current  draw  pointer  position  to  the  point  speci- 
fied by  the  offsets.  The  "bm  li;  drawn  in  the  current  foreground 
color.  The  draw  pointer  returns  to  its  original  location.  This  is 
a  relative  command. 

Code:  IB  49 

Parameters:  HBXo  LBXo  HBYo  LBYo 
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Circle  Draw  Circle 


Function:  Draws  a  circle  of  the  specified  radius  with  the  cen- 
ter of  the  circle  at  the  current  draw  pointer  position.  The  cir- 
cle is  d]sism  in  the  eusraoi  tetpmnd  color.  The  draw  pointer 
remains  in  its  original  location. 

Code:  IB  50 

Parameters:  HBRLBR 
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Ellipse  Draw  Ellipse 

Function:  Draws  an  ellipse  with  its  center  at  the  current  draw 
pointer  position.  The  X  value  specifies  the  horizontal  radius, 
and  the  Y  value  specifies  the  vertical  radius.  The  ellipse  is 
drawn  in  the  current  foreground  color.  The  draw  pointer 
remains  in  its  original  location.  This  is  a  relative  conunand. 

Code:  IB  51 

Parameters:  HBRx  LBRx  HBRy  LBRy 
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FFill  Flood  FiU 

Funetton:  Fills  the  so-ea  whepe  flie  teckpotrnfl  is  the  mme 
color  as  the  draw  pointer.  Filling  starts  at  the  current  draw 
pointer  position,  using  the  current  foreground  color.  The  draw 
pointer  returns  to  its  original  location.  This  is  a  relati'we 
command. 

Code;         XB  4F 
Parameters:  None 


0lS-i  Wimiming 


Line  Draw  Line 


Funeliont  Dra^s  a  line  ft'om  the  ettwent  Afm  pc^tfse*  potion 
to  the  specified  point,  using  the  current  foreground  color.  Ths 
draw  pointer  returns  to  its  original  location. 

Code:  IB  44 

Parameters:  HBX  LBX  HBY  LBY 


RLine  R(dative  Draw  Lane 


Function:  Draws  a  line  from  the  current  draw  pointer  position 
to  the  point  specified  by  the  ofi^ts,  using  the  eurrait  fore- 
ground color.  The  draw  pointer  returns  to  its  cnriginal  location. 

This  is  a  relative  command. 

Code:  IB  45 

Parameters:  HBXo  LBXo  HBYo  LBYo 
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LineM  Draw  line  and  Move 


Function:  Draws  a  line  from  the  cpaBal  itl^  p^ter  position 
to  the  specified  point,  using  the  ettixent  foreground  color.  The 
draw  pointer  stays  at  the  new  location. 

Code:  IB  46 

Parameters:  HBX  LBX  HBY  LBY 


RLineM  Relative  Draw  Line  and  Move 


Function:  Draws  a  line  from  the  current  draw  pointer  position 
to  the  point  specified  by  the  offsets,  using  the  current  fore- 
ground color.  The  draw  pointer  stays  at  the  new  location.  This 
is  a  relative  cotnmand. 

Code:  IB  47 

Parameters:  HBXo  LBXo  HBYo  LBYo 
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Point  Draw  Point 

Function:  Draws  a  pixel  at  tiie  specified  coordinates,  usii^ 

the  current  foreground  color. 

Code:  IB  42 

Parameters:  HEX  LBX  HBY  LBY 

RPoint  Relative  Draw  Point 

Function:  Draws  a  pixel  at  tiie  location  specified  by  the  off- 
sets, using  the  current  foreground  color.  This  is  a  relative 
Gominand. 

Code:  IB  43 

Birameters:  HBXo  LBXo  HBY>  LB% 
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PutGC  Put  Grsiphics  Cursor 

Function:  Puts  and  displays  the  graphics  cursor  at  the  speci- 
fied location.  The  coordinates  passed  to  this  command  are  not 
windoW-iekCfiive.  The  horizontal  Fsenge  ii  0  to  i|9.  The  vertieal 
range  is  0  to  191.  The  default  position  is  0,0. 

This  command  is  useful  for  applications  running  under  Grfint 
so  that  you  can  display  a  graphics  cursor  under  Windint  even 
if  you  don't  want  mouse  control  of  the  cursor. 

Code:  IB  4E 

Parameters:  HBX  LBX  HBY  LBY 
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SetDPtr  Set  Draw  Fbinter 


Function:  Sets  the  draw  pointer  to  the  specified  coordinates. 
The  new  draw  pointer  position  is  used  as  the  beginning  point 
in  the  next  draw  command  if  other  coordinates  are  not 
specified. 

Qotheti  IB  40 

Parameters:  HBX  LBX  HBY  LBY 


RSetDPtr  Relative  Set  Draw  Pointer 


Function:  Sets  the  draw  pointer  to  the  point  specified  by  the 
offsets.  The  new  draw  pointer  position  is  used  as  the  begin- 
ning point  in  the  next  draw  command  if  other  coordinates  are 
not  specified.  This  is  a  relative  command. 

Code:  IB  41 

Parameters:  HBXo  LBXo  HB%  LBYo 
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Text  Commands 


The  tract  commands  let  you  control  the  cursor's  position  and 
movement  and  also  the  text  prints  on  the  display.  These 
commands  can  be  used  m  eMisr  ^Kt  or  graphics  windows. 

The  text  commands  are: 


Code  Desei^itoi 

01  Ikaxm  the  euorsor  . 

02  xy  Positions  carstHr  to  x,y.  Specify  coopitoiates  as 

(*+$20)  and(y+$20). 

03  Erases  the  ciirrent  line. 

04  Erases  from  the  current  character  to  the  end  of 

the  line. 

05  20  Turns  off  the  cursor. 

05  21  Turns  on  the  cursor. 

06  Moves  the  cursor  right  one  character. 

07  Rings  the  bell. 

08  Moves  the  cursor  left  one  character. 

09  Moves  the  cursor  up  one  line. 

OA  Moves  the  cursor  down  one  line. 

OB  Erases  from  the  current  character  to  the  end  of 
the  screen. 

DC  Erases  the  entire  screen  and  homes  the  cursor. 

CD  Sends  a  carriage  return. 

IF  20  Turns  on  reverse  video. 

IF  21  Tvims  off  reverse  video. 

IF  22  Tums  on  underlining. 

IF  23  Tums  off  underlining. 

IF  24  Tums  on  blinking.^ 
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Code 

iJ'Coeviptioii 

IF  25 

Turns  off  blinking.* 

IF  30 

Inserts  a  line  at  the  current  cursor  position. 

IF  31 

Deletes  the  current  line. 

IB  3C  BSW 

See  TCharSw  in  Chapta:  3.^ 

IB  3D  BSW 

See  BoldSw  in  Chapter  3.* 

IB  3F  BSW 

See  PropSw  in  Chapter  3.^ 

Blink  is  not  supported  for  text  on  graphics  screens. 

These  characteristics  are  supported  for  text  on  graphics 
screens  only. 
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Index 


active  window  3-34  buffers  icont^d) 

AND   3-21  screraitype  3-32 

arc,  draw   4-2  size  3-32 

ARC3P  4-2  save  3-18 


background  color   3-2,  3-13 

BAR  4-3 

bar,  draw  4-3 

bar,  relative  draw  4-3 

BCOLOR  3-2 

bell  ,  ri  n  g  5  -1 

blinking    5-1,  5-2 

off  5-2 

on  5-1 
boldface  3-3,5-2 
BOLDSW  3-3,5-2 
BORDER    3-4,  3-26 
border  color    3-4,  3-13,  3-26 
BOX  4-4 
box,  draw  4-4 
box,  relative  draw  4-4 
buffer,  kill  3-20 
buffer,  load  3-19 
buffers  3-7,3-19 
buffers 

close  3-20 

define  3-7 

font  3-19 

^t/put  8-19 

get/put  3-7 

patterns  3-29 
save  3-18 

group  numbers  3-7 

kill  3-20 

load  3-19 

logic  3-21 

pattern  3-29 

16-color  3-31 
2-eotor  3-30 
4-color  3-31 

pattern  array  3-29 

pattern  size  3-29 

put  3-32 

block  3-32 


carriage  return  5-1 
change  font  3-15 
character 

erase  5-1 

transparent  3-35 
GUCI^  4-5 
circle,  draw  4-5 
close  buffer  3-20 
close  overlay  window  3-23 
cbse,  window  3-10,  3-23 
color  8-26 

background    3-2,  3-13 

border    3-4,  3-13,  3-26 

composite  3-27 

defeult  3-6 

foreground   3-13,  3-14, 
3-26 

graphics  3-6 

high-resolution  3-6 

palette  3-26 

RGB  3-26 

VDG-emulation  3-6 
command  parameters  2-1 
commands 

drawing    2-1,  4-1 

general    2-1,  3-1 

text    2-1,  5-1 
composite  colors  3-27 
create  windows 

device  1-2 

overlay  1-4 
current  window   3-13,  3-34 
cursor  3-17 

home  5-1 

graphics  3-17 
put  4-11 

move  5-1 

off  5-1 

on  5-1 
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cursor  (cont'd) 

position  5-1 

set  3-17 
CWAEEA  3-5 

default  color  3-6 

default  windows  1-3 

DEFCOLR  3-6 

define  buffers  3-7 

define  device  windows  3-12 

delete  line  5-2 

device  descriptors    1-1,  3-12 

device  windows  1-1 

background  color  3-13 
border  color  3-13 
color 

background  3-13 
border  3-13 
foreground  3-13 

define  3-12 

end  3-10 

foreground  color  3-13 

keyboaM  3-84 

location  3-13 

process  window  3-13 

protect  3-11 

select  3-34 

set  3-12 
DFNGPBUF  3-7 
DISPLAY  1-2,2-1,3-12 
draw  pointer  4-1 

relative  set  4-12 

set  4-12 

draw 

arc  4-2 
bar  4-3 

bar^,  relative  4-3 
box  4-4 

box,  relative  4-4 
circle  4-5 
ellipse  4-6 
fill  4-7 
flood  fill  4-7 
line  4-8 

line  and  move  4-9 


draw  (cont'd) 

line  and  move, 
relative  4-9 

line,  relative  4-8 

poitrt  4-10 

point,  relative  4-10 

pointer  4-1 
drawing  commands  4-1 
DWEND  3-10 

mmmm  3  -11 

DWSET  1-1,1-2,3-12 

ELLIPSE  4-6 

ellipse,  draw  4-6 
end  overlay  window  3-23 
end  window    3-10,  3-23 
erase  character  5-1 
&c&se  line  5-1,  5-2 
erase  screen  5-1 
erase  to  end  of  screen  5-1 
escape  sequence  1-2 

PCQLOR  3-14 

FFILL  4-7 

fill,  draw  4-7 

flood  fill,  draw  4-7 

FONT  3-15 

font  3-12,3-15,3-19 

bit  map  3-15 

boldface   3-3,  5-2 

change  3-15 

current  3-15 

data  3-15 

load  3-19 

order  3-15 

proportional  3-15,  3-28, 
5-2 

font  bit  map  3-lS 
font  data  3-15 
font  load  3-19 
font  order  3-15 
foreground  color  3-13,  3-14, 
3-26 

GCSET  3-17 


Index 


general  commands   2-1,  3-1 
get/put  buffers 
close  3-20 

define  3-7 
font  3-19 

group  numbers  3-7 

kill  3-20 

load  3-19 

logic  3-21 

patterns  3-29 

put  3-32 

save  3-18 
GETBLK  3-18 
GPLQAD  3-9,3-15,3-19,3- 
32 

graphic  patterns  3-29 
graphics 

boldface  3-3 

colors  3-6 

cursor   3-17,  4-11 
put  4-11 
set  3-17 

font,  proportional  3-28 

transparent  3-35 
group  numbers   3-7,  3-8 

Grp_eiip  3-8 

Grp_Fnt  3-8 

Grp_Pat2  3-8 

Grp_Pat4  3-8 

Grp__Pat6  3-8 

Grp_Ptr  3-8 

high-resolution,  colors  3-6 
home  cursor  5-1 

I$ATTAGH  3-10 
immortal  shell  1-3 
INIZ    1-2,  3-10,  3-12 
insert  line  5-2 
interactive  window  3-34 

KILBUF  3-20 
kill  buffer  3-20 


LINE  4-8 
line 

draw  4-8 

erase    5-1,  5-2 

insert  5-2 

relative  draw  4-8 
Bne  and  msim,  Qmm  4-9 
line  and  move,  relative  draw 
4-9 

LINEM   4-1,  4-9 
load  get/put  3-19 
load  font  3-15,3-19 

location,  window  3-13 
logic  operations   3-21,  4-1 
logic  set  3-21 
LSET  3-21 

memory    1-1,  3-12 
MONTYPE  3-6 
move  cursor  5-1 

open  windows 

device  1-2 

overlay  1-4 
OR  3-21 

overlay  window   1-1,  1-2,  3-23, 

3-24 
overlay  window 

end  3-23 

no-save  3-24 

save  3-24 

select  3-34 

set  3-24 

size  3-24 

stacked  3-25 
OWEND  3-23 
OWSET    1-4,  3-24 

PALETTE  3-26 
palette  colors  3-26 

parameters,  command  2-1 
pattern   3-29,  4-1 

16-color  3-31 

2-color  3-30 
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pattern  (cont'd) 
4-color  3-31 

size  3-29 
POINT  4-10 
point,  draw  4-10 
point,  relative  draw  4-10 
pointer,  draw  4-1 
position  cursor  5-1 
process  window  3-13 
proportional  characters  3-28, 
5-2 

proportional  font  3-28 
PROPSW   3-28,  5-2 
protect  device  windows  3-11 
PSET  3-29 
put  block  3-32 
pot  buffer  3-32 

screen  type  3-32 

size  3-32 
put  graphics  cursor  4-11 
PUTBLK  3-18,3-19,3-32 
PUTGC  4-11 

REAR  4-3 

mm.  4-4 

reverse  video  S-1 
RGB  colors  3-26 
ring  bell  5-1 
RLINE  4-8 
RLINEM  4-9 
RPOINT  4-10 
RSETDPTR   4-1,  4-12 

save,  get/put  3-18 
save  wiiMMiw  S-IS 
SCALESW  3-33 
scaling  3-33 
scaling,  automatic  3-33 
scaling  coordinates  3-33 
screen  type  3-12 
screen,  erase  5-1 
SELECT  3-34 
select  window  3-34 


set 

device  window  3-12 
draw  pdnEter  4*12 
draw  pointer,  relative 

4-12 

overlay  window  3-24 
SETDPTR  4-1,4-12 
SETOTAT  3-8 
SHELL  1-3 
shell,  fork  1-3 

stacked  overlay  windows  3-25 

TCHAisw  m 

text  commands  5-1 

text 

boldface   3-3,  5-2 
proportional   3-28,  5-2 
transparent  character  3-35, 
5-2 

underline 

off  5-1 
on  5-1 

video,  reverse  5-1 

WCREATE  1-2 
windows  1-1 

background  color  3-2, 
3-13 

bold&ce  3-3,5-2 
border  color  3-4,  3-13, 

3-26 

buffers    3-7,  3-19 

kill  3-20 

load  3-19 

patterns  3-29 

put  3-32 
close   3-10,  3-23 
color  3-26 

background  3-2, 
3-13 

border   3-4,  3-13, 

3-26 
composite  3-27 
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windows  {cont'd) 

default  3-6 
teeground  3-13, 

3-14,  3-26 
RGB  3-26 
current  3-13 
cursor  3-17 
default  1-3 
default  color  3-6 
device  1-1 

define  3-12 
end  3-10 
opening  1-2 
protect  3-11 
select  3-34 
set  3-12 
device  descriptors  1-1, 

3-12 
end  3-10 
fonts    3-15,  3-19 
foreground  color  3-13, 

3-  14,  3-26 
graphics  cursor  3-17, 

4-  11 

interactive  3-34 
keyboard  3-34 
location  3-13 
logic  operations  3-21 
maximuin  1-1 


windows  {cont'd) 

memory    1-1,  3-12 

<me\m  1-1, 1-2,  3-23, 
3-24 

end  3-23 
no-save  3-24 
opening  1-4 
save  3-24 
select  3-34 
set  3-24 
size  3-24 
stacked  3-25 

process  window  3-13 

process  3-13 

protect  3-11 

put  buffer  3-32 

save  3-18 

scaling  3-33 

screen  type  3-12 

select  3-34 

size  3-5 

transparent  mode  3-35, 

5-2 
type  1-1 
work  area  3-5 
work  area  3-5 

XOR  3-21 
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active  processes.   Operations  that  the  system  is  currently 

executing. 

active  state.  An  operating  or  working  condition.  A  procedure 
in  an  active  state  is  processing  data  and  not  waiting  for  anothra" 
procedure  to  end. 

addymss,  A  number  that  identifies  a  location  in  your  comput- 
er's memory. 

age.  A  count  of  the  number  of  switches  ^omm  llhanges)  the 
system  1ms  made  since  a  process's  last  time  slice, 

anonymous  directory.  A  directory  referenced  by  its  hierarchi- 
cal position  using  the  period  (.)  character.  One  period  refers  to 
the  current  directory.  Two  periods  refer  to  the  parent  (rf  the  cur- 
rent directory,  md.  so  on. 

application  program.  A  process  or  group  of  processes 
designed  to  accomplish  specific  tasks,  such  as  word  processing, 
data  management,  game  plying,  and  so  on. 

argument.  Data  you  supply  to  a  process  or  command  fot  it  to 

evaluate. 

array.  Data  arranged  so  that  each  item  is  located  by  its  row 
and  column  positicai.  Single-dimensioned  aimyi  hme  one  or  more 
rows  and  one  column.  Multi-dimensioned  arrays  have  one  or 
more  rows  and  two  or  more  columns. 

ASCII  code.  American  Standard  Code  for  Information  Inter- 
change. A  method  of  defining  alphabetic  and  numeric  characters 
and  other  sjonbols  by  giving  each  a  unique  value.  For  instance, 
the  ASCII  value  for  A  is  6S,  and  the  ASCII  value  for  B  is  66. 

m8&mM0t^  A  pop-W  that  produces  macbite^  code  £i*om  source 
code  (code  from  a  low-lewd  computer  language). 

assembly  language.  A  system  for  coding  computer  instruc- 
tions to  perform  tasks.  You  can  use  assembly  language  code  to 
directly  manipulate  data  within  a  computer;  therefore,  assembly 
language  needs  less  interpretation  than  higher  level  languages 
like  BASIC  or  Pascal. 

attribute.  See  file  attribute. 
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background  processing.  Executing  one  or  more  procedures 
and  at  the  same  time  continuing  to  operate  in  OS-9  or  in 
another  procedure. 


backup.   An  identical  copy  of  the  contents  of  one  disk  on 
ajiother  disk. 

base.  The  lowest  value  allowed  in  a  function  or  operation.  For 
instance,  BASIC09  allows  a  base  value  of  1  for  array  structures 
unless  you  indicate  otherwise, 

batch  file.  See  procedure  file, 

baud.   Bits-per-second.  A  unit  for  measuring  the  speed  of  data 
flow  between  devices. 

binary.  A  numbering  system  using  only  two  digits,  0  and  1.  In 
this  system,  shifting  the  position  of  a  digit  to  the  left  raises  the 
value  of  the  digit  by  the  power  of  2.  For  instance,  1  is  the  binary 
equivalent  of  1,  10  =  2,  100  =  4,  1000  =  16,  and  so  on. 

bit.    The  smallest  unit  of  a  computer's  memory.  Eight  bits  form 
a  byte.  Each  bit  can  have  a  value  of  either  0  or  1. 

bit  map.  A  storage  area  of  256  l>ytes.  Each  bit  represents  one 
page  (256  bytes)  of  your  computer's  memory.  If  a  bit  is  set 
(equals  1)  then  its  associated  memory  page  is  allocated.  If  a  bit 
is  reset  (equals  0)  then  its  associated  memory  page  is  free. 

block.   A  group  of  data,  often  comprising  256  bjrtes. 

block-oriented  device.   A  device  that  receives  data,  sends 

data,  or  both,  in  groups  of  256  bytes. 

Boolean  logic.   A  binary  type  of  algebra  developed  by  George 
Boole, 

Boolean  data  type.  A  type  of  variable  that  can  have  only  two 
values,  True  or  False.  Boolean  data  types  usually  store  the 
results  of  comparisons,  such  as:  is  A  greater  than  B  (A>B),  does 
Y  equal  X  (Y=X),  and  so  on, 

boot.  The  process  of  loading  and  initializii^  OS-9. 

bootfile.  A  disk  file  containing  modules  to  be  loaded  during  an  _ 
OS-9  boot. 

bootlist.   A  disk  file  containing  a  list  of  module  names  to  be 
used  by  0S9Gen  to  create  a  bootiB.le. 
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bootstrap  module.  A  program  that  contains  the  code  neces- 
sary to  initialize  OS-9. 

border.  An  area  around  a  screen  or  window  that  defines  the 
boundaries  of  the  screen  or  window. 

branch.  lb  leave  one  fouliiie  and  beg$n  esecution  oS  another 
routine  within  a  progiroi  or  poeedure. 

breakpoints.  Locatictas  in  a  program  or  procedure  at  which 
you  wamt  essem&Q  to  pause. 

bu£G^.  A  temporary  storage  area  through  which  08-9  trans- 
fers data. 

byte.   A  unit  of  computer  memory  storage  that  contEuns  a  value 

in  the  range  0-255. 

byte  data  type.  A  numeric  type  of  variable  that  can  contain 
unsigned  eight-bit  integ^  data  (in  the  range  0-255  decimal). 

call.  (1)  To  transfer  execution  to  another  routine,  then  return 
to  the  calling  procedure  with  obtained  values  intact  and  avail- 
able for  use  by  the  calling  routine.  (2)  A  built-in  OS-9  routine 
that  performs  a  system  function. 

CCSDisk.  The  floppy  diskette  driver  module. 

CC3IO.  The  system  input/output  driver. 

chaining.   A  process  of  calling  and  turning  over  system  control 

to  a  new  procedure. 

checksum.  A  value  calculated  from  the  contents  of  a  file  or 
m0dule  that  the  system  can  later  use  to  verify  iis^iether  the  con- 
tents of  the  file  or  module  are  uncorrupted. 

child  or  child  process.  A  process  begun  frcm  another  (par- 
ent) process. 

close.   The  process  of  deallocating  the  path  to  a  device  or  file. 

cluster.  A  group  of  sectors.  In  OS-9  for  the  Color  Computer,  a 
clusta:  consists  of  only  one  sector. 

code.   Numeric  data  that  can  be  used  by  a  computer  to  perform 

a  task. 

command.   The  name  of  an  OS-9  program  or  function. 
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command  line.  One  or  more  cammands  with  all  their  parame- 
ters, options,  and  modifiers. 

command  modifiers.  Data  or  values  appended  to  a  command 
that  chanip  the  way  the  command  fimctions. 

command  options.  Data  ftat  you  can  include  in  a  command 
line  to  specify  the  way  the  command  functions. 

cmsmssiA  j^mwUBt^SS.  Data  or  values  appended  to  a  com^ 
mand  timt  define  or  customize  tibe  command. 

command  separator.  A  semicolon.  '%)U  can  Mm  a  semleolim  to 
separate  several  commands  on  the  same  command  line. 

compile.  To  create  machine  language  code  (object  code)  from  a 
program  written  with  a  computer  language.  Also  to  translate 
high  level  code  (from  a  high  level  language  such  as  BASIC)  into 
low  level  code  (code  that  is  like  machine  language). 

complement.  A  value  that  is  derived  by  subtracting  a  number 
from  a  constant.  Pbr  example,  the  10s  complement  of  4  is  6.  In 
binary,  a  value  is  complemented  by  changing  all  the  1  digits  to  0 
and  all  the  0  digits  to  1,  then  adding  1  to  the  least  significant 
(ligjbtiaioirfl  dipt. 

complrat  daM  skficiiire.  A  group  of  data  that  contains  two  or 
more  %p@S  of  data  structures.  See  data  structure. 

constant.  A  value  or  block  of  data  that  is  fixed  (does  not 
change  during  the  run  of  a  program  or  procedure). 

CPU.  Central  Processing  Unit.  An  integrated  circuit  (chip) 
t^t  contrds  the  operation  of  a  computer. 

current  directory.   The  directory  in  which  OS-9  looks  for  data 

files  or  stores  data  files  unless  you  specify  otherwise. 

current  line.  When  editing,  the  line  on  which  the  editing  cur- 
sor or  painter  is  located. 

cursor  (te3£l)»  A.  oolerad  hox  that  sham  v0mte  l&e  next  charac- 
ter is  to  appeaf  Wt  &m  samm,  A  text  cursor  appears  cm  both  text 
and  graphics  windovra  or  screws. 

cyclic  redundancy  check  (CRC).  A  value  the  system  calcu- 
lates from  the  data  stored  in  a  module.  The  system  calculates  a 
new  value  each  time  it  attempts  to  load  the  module.  If  the  calcu- 
lated value  does  no*  match  the  CRC  value  contained  in  the  mod- 
ule, the  system  cannot  load  the  module. 
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cylinder.  A  disk  track  that  includes  both  sides  of  a  disk.  See 
also  track. 

DAT.  Dyneimic  address  translation.  The  memory  management 
system  used  by  OS-9  Level  Two. 

data  directory.    The  directory  in  which  08-9  automatically 

saves  files  unless  you  specify  otherwise. 

data  structure.    A  unit  of  data,  organized  for  access. 

data  type.  A  method  for  representing  data,  such  as  character 
(ASCn  valuej,  iait^er  (whole  number),  or  real  (floatiBg  point 
number). 

d^idUock.  See  dmSi^  embrace, 

deadly  embrace.  A  situation  in  which  two  processes  attempt 
to  gain  control  of  the  same  disk  areas  at  the  same  time. 

debug.    To  find  and  correct  program  errors. 

decompile.  To  translate  machine  language  code  into  a  com- 
puter language  code. 

delimiter.  A  character  that  divides  items.  For  instance,  in 
OS-9,  the  semicolon  is  a  delimiter  that  divides  two  commands  on 
the  same  line. 

descriptor.  See  device  descriptors. 

device.  A  data  source,  destination,  or  both.  OS-9  devices  can 

exist  in  your  computer's  memory  (such  as  a  window  or  a  RAM 
disk),  or  they  can  be  external  equipment  (such  as  a  printer  or 
disk  drive). 

device  descriptors.  Small  tables  that  define  a  device,  its 
name,  its  driver,  and  its  file  manager.  Device  descriptors  also 
contain  port  initializatiW  data  and  port  address  information. 

dentiiee  drivers.  Modules  that  handle  basic  itiput/output  &m&- 

tibns  for  specific  devices.  Each  device  you  use  with  your  computer 
must  have  its  own  driver  to  interpret  the  code  you  send  it. 

device  name.  A  unique  system  word  for  a  device.  The  name  for 
disk  Drive  0  is  /DO,  the  nsme  for  Window  1  is  /Wl,  and  so  on. 

device  table.  See  device  descriptor. 
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device  window.  An  OS-9  device  from  which  yoti  ma  ttm  a 
program  or  utility.  Access  device  windows  in  the  same  manner 
as  you  do  other  devices.  Each  device  window  has  its  own  input 
and  output  buffers.  Refer  to  windows  using  device  names  (AV  fol- 
lowed by  a  number),  such  as  /Wl,  /W2,  AV3,  and  so  on. 

directory.  A  file  in  which  OS-9  stores  a  list  of  other  files, 
including  their  names,  locations  on  the  disk,  attributes,  and  so 

on. 

disk  allocation  map.  Logical  Sector  Number  1  on  a  disk.  The 
data  in  LSNl  indicates  which  sectors  are  allocated  to  files  and 

which  sectors  are  free. 

double  click.  To  press  and  release  the  mouse  button  twice  in 
qiiick  succession  when  the  pointer  is  over  the  desired  location. 

drag.  lb  hold  down  the  mouse  button  and  miove  the  mouse  to  a 
new  position  before  releasing  the  button. 

draw  pointer.  An  indicator  that  detenchilies  where  the  next 
graphics  draw  command  will  begin  unless  you  specify  otherwise. 

driver.   -See  device  driver. 

dump.  To  write  the  contents  of  a  video  screen,  a  memory  loca- 
tion or  a  file  to  another  terminal,  memory  location,  or  fLle. 

echo.  To  cause  data  being  sent  to  one  device  to  go  to  another 

device,  as  well. 

edit.  To  change  the  data  or  values  in  a  file  or  in  your  comput- 
er's naemory. 

edit  hmttm.  Am.  allemtte  workspace  for  the  OS-S  Maero 
Editor. 

edit  macro.  A  series  of  commands  you  can  execute  with  only  a 
single  command. 

edit  pointer.  An  indicator  that  determines  where  the  next  edit 
command  is  to  ^erate  iml^s  pta  sped%'  otherwise. 

editor.  A  program  that  provides  special  commands  to  aid  you 
in  changing  the  contents  of  a  file. 

error  code.  A  code  that  OS-9  displays  when  it  cannot  under- 
state what  you  want  it  to  do  or  wh^  your  computer  or  a  peri^- 
eral  malfunctions.  Use  the  displsQred  code  number  to  look  up  a 
description  of  the  error. 
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error  path.  The  route  through  which  OS-9  sends  error  codes 
and  other  information  to  display  on  the  screen.  The  error  path  is 
designated  as  Path  Number  2. 

error  trap.  A  routine  in  a  procedure  that  checks  for  an  error 
and  provides  an  alternate  action  (other  than  terminating  eJfficu- 
tion  smi  displaying  a  system  &wx  rm^s^}- 

exemtable  file.  A  program  file  that  fm  mM  two.  by  typing 
and  entering  its  filename. 

execute.   Tb  start  a  xirocedure,  program,  or  command  (cause  it 

to  run). 

execution  directory.  The  disk  directory  that  contains  your 
system's  command  files. 

execution  modifiers.  See  command  modifiers. 

^racution  offset.  The  location  in  a  program  or  subroutine  at 
which  execution  begins,  calculated  fi'om  the  beginning  of  the 
module. 

expressions.  Data  items  joined  by  arithmetic  operators.  See 
also  op^ator. 

expression  stack.  A  memory  location  in  which  BASIC09 
stores  temporary  results  while  it  evaluates  an  expression. 

file.  (1)  A  block  of  information  your  computer  uses  for  a  partic- 
ular function  or  program.  A  file  can  contain  an  operating  sys^ 
tem,  a  language,  an  application  program,  or  text.  (2)  A  collection 
of  associated  records,  such  as  information  about  each  book  in  a 
library. 

file  attribute.    Data  that  identifies  a  file,  for  instance  its  size, 

security  status,  language  type,  and  so  on. 

file  locking.  Protecting  a  file  to  ensure  that  one  process  does 
not  change  it  while  another  process  is  using  it. 

file  pointer.  An  indicator  that  detenun^  'w^jere  in  a  file  the 
next  read  or  write  operation  is  to  occur  unless  you  or  the  system 
indicates  otherwise. 

file  security.  A  set  df  attributes  that  determines  who  can  use 
a  file  and  in  what  manner. 

filename.    A  set  of  characters  that  uniquely  identifies  and 

locates  a  block  of  data  stored  on  a  disk. 


filter.    To  alter  data  in  some  manner  as  it  passes  between  two 

devices  or  between  two  memory  locations. 

flag.  A  symbol  or  value  that  indicates  when  a  certain  condition 
exists  in  a  procedure. 

tmk  A  i^kmraiAer  set.  A  group  of  alphabetic  and  numeric  char- 
aet^s  and  other  symbols  of  a  particular  style  and  shape. 

foreground.  (1)  An  OS-9  task  that  takes  priority  over  other 
concurrently  running  tasks.  (2)  Characters  or  designs  on  a 
screen  or  window. 

fork.   The  process  of  initializing  one  procedure  from  another 

procedure. 

format.  To  magnetically  organize  a  diskette  so  that  the  com- 
puter can  use  it  to  store  data. 

itmolian.  M  BA^OQ®,  an  opemtion  tefe  l^^HS  ]ser&rms  on 
(iata.  A  &m^hm.  aim^e  relunis  (|rate;es) «  value  of  some  type. 

Gret/Put  buffer.  A  buffer  in  which  you  or  the  system  can  store 
fonts,  screen  patterns,  graphic  displays,  overlay  windows,  and 
other  recallable  data.  The  system  allocates  Get/Put  buffers  in  8- 
kilobyte  blocks. 

getstat.  An  OS-9  routine  that  gets  (returns)  the  state  or  status 
<k  a  specific  system  operation. 

gMid  ■vlKlletble.  A  variable  that  is  available  to  all  p^oeediMs 
and  routines  in  a  program. 

graphics.   An  arrangement  of  demmts  flines,  dots,  and  so  on) 

on  your  computer's  screen. 

graphics  cursor.  An  indicator  (either  visible  or  invisible)  that 
determines  where  the  next  graphic  function  is  to  occur  on  the 
screen  vmless  you  or  a  program  specifies  otherwise.  In  applica- 
tions, you  Q^m.  move  the  ^aphics  cursor  using  a  mtmse. 

graphics  point^i  See  graphics  cuxs^. 

grapMes  screen.   A  screen  in  which  all  pixels  are  represeatfced 

by  bits  in  a  memory  map.  "You  create  images  on  the  screen  by 
manipulating  the  bits  using  special  OS-9  or  computer  language 
commands. 
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graphics  window.  A  window  created  on  a  graphics  screen. 
You  can  display  both  graphics  (drawn  iinaips)  and  text  on  a 
graphics  window.  The  text  gtaaea'ated  m  a  gmphies  madow/ 
screen  uses  software  fonts  that  you  or  the  system  must  bad  into 

memory. 

group.  An  organization  of  related  data  or  files.  For  instance, 
OS-9's  graphics  buffers  are  organized  into  groups  that  you  refer- 
ence by  number. 

hardware.  The  physical  parts  of  your  computer,  including  its 
disk  ^ves,  keyboard,  integratlsd  cir&uits  (chips),       m  an< 

hs&Bm.  Data  located  at  the  beginning  of  a  f!le  m  module  to 
ideisfeiJ^  its        size)  vmfication  values,  and  so  <m. 


hexadecimal.  A  number  system  to  a  base  of  16  (using  16  dig- 
its). Hexadecimal  digits  are  0,  1,  2,  3,  4,  5,  6,  7,  8,  9,  A,  B,  C^D, 
E,  and  F.  Shifting  a  hexadecimal  digit  one  place  to  left 
causes  its  value  to  be  multiplied  by  16. 

hig]i  order  bit.  The  most  significant  or  leftmost  bit  in  a  byte. 
If  the  high  xaSet  bit  is  0,  it  repres^s  a  value  of  Q.  If  tlie  Mgh 
order  bit  is  1,  it  represents  a  value  of  128. 

I/O.  Input/Output. 

identification  sector.  Logical  Sector  Number  0  on  a  disk. 
LSNO  contains  a  description  of  the  physical  and  logical  organiza- 
tion of  a  disk. 

immortal  shell.   An  OS-9  shril  tlmt  does  not  die  on  receiving 

an  EOF  signal  (such  as  when  you  press  |  ctrlH  break]). 

integer  data  type.  A  type  of  variable  that  can  store  whole 
numbers  in  the  range  -32768  to  32767. 

interactive  window.  A  window  that  is  getting  input  from  the 
k^board.  This  window  is  currently  on  the  displayed  screen. 

interface.   To  link  devices  or  modules  together  in  order  to 

transfer  data. 

internal  integrity  check.  A  system  of  internal  values  that 
OS-9  eaift  use  to  make  certain  that  its  system  modules  and  func- 
tions are  accurate. 

lOMAN.  The  input/output  manager  that  provides  common  pro- 
cessing for  all  input/output  operations. 
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IRQ.  Interrupt  request.  A  signal  that  causes  the  execution  of 
one  process  to  halt  and  the  execution  of  another  process  to  begin. 
Tim  sj^ilem  relstei  iihe  mbes  of  the  first  process  so  that  it  can 
lat^  contiiiue  its  elation. 

kernel.  OS-9  software  that  supervises  the  OS-9  system  and 
provides  basic  system  services,  such  as  multitasking  and  memory 
managem^t,  said  that  links  all  system  modules. 

key  sequence.   Two  or  more  keys  you  press  at  the  same  time  to 

produce  a  specific  function. 

keyboard  mouse.  An  OS-9  function  that  lets  you  use  the  key- 
board  arrow  keys  instead  of  an  exteroal  mouse  device.  Press 
I  CTRL  II  clear!  to  toggle  the  k^board  mouse  on  and  off. 

keyword.  A  command  name. 

kill.  Terminate  the  execution  of  a  process. 

kjlbl^yte.  1024  Iptes. 

link.  To  make  a  modi^  ovi^Ui^  to  m  T^m&m^ 

link  count.  The  number  of  processes  using  a  module.  When  a 
module's  link  count  reaches  0,  OS-9  deallocates  the  module. 

load.  To  transfer  data  from  an  external  device  into  your  com- 
puter's memory. 

local  variable.  A  variable  that  can  be  used  by  only  the  proce- 
dure or  routine  in  which  it  resides. 

locked.   See  file  locking. 

lockout.    See  file  locking. 

log  in.  To  initiate  the  necessary  procedure  to  operate  OS-9 
from  a  separate  terminal  (type  in  a  user  name  and  password). 

logical  address.  An  offset  address.  An  adcbress  that  is  Wn- 
bered  from  the  beginning  of  a  block  rather  than  from  the  begin- 
ning of  memory,  a  module,  or  other  storage  area. 

logical  sectors.  Sectors  that  OS-9  or  a  program  references  in 
numeric  order,  regardless  of  their  actual  physical  location  on  a 
disk. 

loop.  A  sequence  of  BASIC09  commands  that  execute  repeat- 
^y  a  specified  number  of  times  or  until  a  specific  concUtion 
occurs  to  terminate  the  execution. 
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macro.  A  series  of  commands  you  can  ^lecute  with  only  a  sin- 
gle command  name. 

map.   See  memory  map. 

mask.  A  pattern  of  bits  that  you  use  in  combination  with  a 
logical  operator  to  change  specified  data  selectively  —  reversing 
certain  bits  without  affecting  the  others. 

megabyte.    One  million  bytes. 

memory.  The  portion  of  your  computer  that  stores  data  and 
mines. 

memory  management.  Assigning  and  mapping  m^o^y  to 
keep  track  of  modules  (processes  and  data)  and  their  uses. 

memory  map.   A  chart  depicting  the  use  of  your  computer's 

memory  by  the  operating  system. 

menu.  A  screen  display  from  which  you  select  an  action  for 
your  computer. 

microprocessor.   An  integrated  circuit  (chip)  that  controls  the 

basic  operation  of  your  computer. 

mode.    A  particular  function  of  a  program  or  system. 

modem.  Modulator/demodulator.  A  device  to  prepare  signals 
for  transmission  through  telepihone  lines  and  to  reverse  the  pro- 
cess after  transmission. 

modifier.  See  command  modifier. 

module.   An  OS-9  program  w  block  of  data  residing  in  your 

computer's  memory. 

module  body.  A  module's  code  (program  or  data),  including 
the  module  name. 

module  directory.    A  table  in  your  counter's  manory  that 

lists  all  the  modules  residing  in  memory. 

module  header.  Code  that  resides  at  the  beginning  of  all  mod- 
ules and  that  contains  information  ahotti  moiuJe^  itaMMlxg 
size,  type,  attributes,  storage  requirements,  and  its  execution 

starting  address. 

monitor.    The  video  display  device  connected  to  your  computer. 
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mouse.  A  device  you  use  to  control  a  pointer  on  the  display 
screen.  In  application  programs,  you  can  often  use  a  mouse  to 
indicate  functions  you  want  to  initiate. 

multi-programming.  A  method  of  computer  operation  in 
which  the  system  allocates  slices  of  execution  time  to  more  than 
one  process  in  order  to  @cecute  them  Goncur{!@Eil^« 

multi-tasking.  Executing  more  than  one  process  at  the  same 
time. 

multi-user.  A  system  that  lets  more  than  one  p^on  access  its 
functions  at  the  same  time. 

nesting.  Incorporating  one  structure  into  another  structure  of 
the  same  type.  Both  procedures  then  retain  their  individual 

identities. 

non-shareable  file.  A  file  or  module  that  can  be  used  by  only 
cam  |toe@dt^e  or  wmf  &t  &m  time. 


nidi  stiaxtgt  A  sMng  variable  that  does  not  contain  a  V£due 


ol^ject  eQde»  Hidiune  language  ixtEirtxctions. 

offset.  The  difference  between  a  location  and  a  beginning  loca- 
tion. For  instance,  you  can  tell  some  BASIC09  graphics  functions 
to  begin  operation  at  a  location  that  is  offset  from  the  current 
draw  pointer  position. 

operand.  A  value  that  is  used  or  manipulated  during  an  op^- 
alixm  ot  during     as»tmlto  ^  an  xci^mMoii. 

opcarating  system*  A  set  of  associated  programs  tibtt  carry 
out  your  cQixmandSt 

operator.    A  symbol  or  word  that  signifies  some  action  to  be 

performed  on  specified  data. 

options.   See  command  options. 

output  path.  The  route  through  which  the  system  sends  data 
from  one  device  to  another. 

overflow.    A  condition  in  which  a  storage  space  is  not  large 

enough  to  contain  the  data  sent  to  it. 

overlay.  A  condition  in  which  programs  or  modules  in  a  com- 
puter's memory  are  replaced  with  other  data. 
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overlay  window.  A  window  opened  or  placed  on  top  of  a  device 

window. 

overwrite.    To  replace  data  with  other  data. 

owner.  An  entity  that  has  control  over  a  file,  module,  or 
process. 

pack.   To  compile  a  BASIC09  procedure.  See  compile. 

psidding.  Adding  spaces  to  a  strii^  or  unit  of  data  to  make  it 
a  specific  length. 

page.    In  your  computer's  memory,  a  block  of  256  bytes. 

paint.    To  fill  all  or  a  portion  of  the  screen  with  a  color. 

palette.  A  register  that  contains  a  numeric  code  representing  a 
mim  m  shade. 

•pm&Emtn^ts.  See  command  fwrnn^^ms. 

parent  or  parent  process.  A  process  tihat  ferks  (starts) 
another  process  (a  child  process). 

parity.  A  system  in  which  all  binary  numbers  of  a  code  are 
converted  to  either  even-bit  numbers  (an  even  number  of  Is)  or 
odd-bit  numbers  (an  odd  number  of  Is). 

parse.  Tb  search  through  a  list  or  sequence  of  data. 

Pascal.   A  high-level  computer  language. 

pass  by  value.  When  BASIC09  passes  a  value  firom  one  proce- 
dure to  another  by  evaluating  a  constant  or  expression  and  plac- 
ing the  result  in  temporary  storage  to  be  accessed  by  the  second 
procedure. 

pass  by  reference.  When  BASIC09  passes  a  variable  from  one 
procedure  to  another  by  providing  the  second  procedure  with  the 
address  of  tiie  variable's  storage. 

passive  window.  Any  window  that  is  not  receiving  input  from 
the  keyboard.  A  process  can  be  running  on  a  passive  window 
provided  ^mt  tie  process  is  getting  its  input  from  a  soiree  oilier 
than  the  keyboard. 
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pathlist.   The  route  from  one  position  in  a  disk's  directory  to 

another  directory  or  file. 

peripherals.  Devices  connected  to  your  computer,  such  as 
ptalgi'S^  IKIdt  fUms,  and  so  on. 

penxdssicSi.  The  attributes  of  a  file  or  module  that  determine 
yfbo  can  use  the  file  or  module  and  in  what  mann^. 

physical  sectors.  The  actual  arrangement  of  sectors  on  a 
disk's  surface,  regardless  of  any  internal  organization  by  OS-9. 

pipe.  A  function  in  which  the  output  of  one  process  becomes 
the  input  of  another  process. 

pipeline.  A  series  of  commands,  each  of  which  passes  the 
results  of  its  operations  to  the  next  command  in  the  series. 

PIPEMAN.  The  pipe  file  manager.  Pipes  are  memory  buffers 
ae^iiag  as  &m  to  ^^ii^ir  dAta  het«v@@n  p^cssMi. 

^Bm  snallii^  area  of  a  displs^  screen  that  can  be  manip- 

pointer.  An  indicator  that  detennines  a  location  in  memory,  in 
a  file,  or  on  the  screen. 

port.  A  junction  between  devices  through  which  data  flows.  An 
electrical  cmnection  bet'ween  jrour  computer  aiid  a  periidxeral. 

position  independent  module.   A  module  that  med  not  be 

loaded  at  any  certain  location  in  memory. 

procedure.    A  program  or  routine  your  computer  can  execute. 

procedure  file,  A  file  containing  one  or  more  OS-9  commands. 
taa  can  ese^te  a  jroeediiaie  file  in  the  same  manner  as  you  ese- 
cute  0^9  ciMMai^  m  j^ge0ms. 

process.   A  computer  program  or  a  routine  that  perfiirms  a 

specific  task  as  part  of  a  computer  program. 

process  descriptor.  A  block  of  data  that  includes  information 
about  a  process,  its  state,  memory  allocations,  priority,  queue 

pointers,  and  so  on. 

process  ID.  A  vmique  numbra-  the  system  gives  each  process  it 
raecutes. 
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process  priority.  A  value  you  or  the  system  gives  to  a  process 
that  determines  the  amount  of  CPU  (execution)  time  it  is  to 
receive  in  a  multi-ta^ng  environment. 

process  state.  The  condition  of  a  process  in  regard  to  eses- 

cution.  A  process  can  be  active  (executing),  waiting  (awaiting  its 
turn  for  processing),  or  sleeping  (inactive  until  it  receives  a  sig- 
nal to  awaken). 

program.    Code  that  causes  your  computer  to  perfinm  some 

function  or  a  series  of  functions. 

program  modules.  Executable  code.  Modules  you  can  run  to 
$m&ma  a  fUnction  or  series  c£  functions. 

pvttdic.  Ax^  mm  of  a  pt>gram  or  module  other  than  the  owner. 
See  owner. 

purge.   Delete.  Usually  refers  to  removing  all,  or  a  sdected 

group,  of  files  from  a  directory. 

RAM.  Random  access  memory.  Computer  memory  you  can 
write  to  (change)  and  read  from. 

BAM  disk.  A  portion  of  your  computer's  memory  that  OS-9 
can  use  &r  data  storage  and  retrieval  in  the  same  manner  as  it 
uses  an  external  dl^  drive.  Howiever,  be  c^ain  you  copy  RAM 
disk  data  to  a  floppy  diskette  or  hard  disk  before  you  exit  OS-9 
or  turn  off  your  computer.  If  you  do  not,  the  data  is  lost. 

random  access.  Reading  (accessing)  information  in  a  block  of 
data  without  first  having  to  read  any  preceding  data. 

raw  data.   Unformatted  information  that  is  passed  to  a  device 

exactly  as  it  exists. 

RBF.  The  random  block  file  manager  that  processes  all  disk 
input/output. 

]fe>i-entrant  prograias.  Programs  or  modules  tSiat  can  be  used 
by  more  than  one  process  at  the  same  time. 

read.   The  process  of  transferring  data  from  a  device  into  the 

computer's  memory. 

read  permission.  System  permission  to  read  (withdraw  data 
firom)  a  file. 
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real  data  type.  A  type  of  variable  that  can  store  floating  point 
numbers  in  the  range  ±1  x  10-^^ 

record.  A  collection  of  related  data  items  that  a  program  or 
P^si  coecisMerg  to  be  a  tOiit  §st  Ihe  purpose  of  processing.  A 
subdivision  of  a  file,  such  as  all  ii^nnation  about  a  single  item 

in  an  inventory  file. 

record  locking.  Protecting  a  portion  of  a  file  to  ensure  that 
one  process  does  not  change  it  while  anothra'  process  is  using  it. 

recursive  procedure  or  routine.  A  procedure  or  routine  that 
r^eatedly  executes  itself  (j^hat  contains  a  statement  causing  it 
to  run  itself  one  or  more  tones}. 

register.  A  location  withia  a  computer's  memory  (often  in  the 
CPU)  for  storing  A^ues  dining  arithmetic,  logic,  or  transfer 

operations. 

remarks.  Text  contained  in  a  program  that  describes  the  pro- 
-am itself  and  that  is  not  to  be  esecuted. 

ROM.  Read  only  memory.  Compoter  memory  containing  con- 
stant values  that  the  computer  can  read  but  cannot  change. 

ROOT  directory.  The  parent  directory  of  all  files  and  directo- 
ries on  a  disk.  The  ROOT  directory  is  created  by  FORMT. 

rutt.  To  messaim,  or  to  cause  a  program  or  procedure  to  stsut. 

masd^mm.  Tim  duration  of  a  program's  execution. 

The  sequential  character  file  manager  that  handles  mm.- 
disk  input/output  operations  to  devices  such  as  printers  and 

terminals. 

scratched.  Destroyed.  When  you  copy  one  file  over  another  file, 
or  the  contents  of  one  disk  onto  another  disk,  any  data  existing 
in  the  second  file  or  on  the  second  disk  is  scratched. 

sector.  A  division  of  a  disk  track.  Disk  tracks  are  organized 
into  sevi^al  sectors. 

seek.  To  position  a  file  pdnfcer  at  a  sp^&  }sy^  loeatte  la  a 
file. 

semigraphics.  Graphics  (designs  on  the  display  screen)  using 
ASCII  graphic  characters. 
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sequential  access.   "Die  process  of  reading  data  in  order,  one 

character  at  a  time. 

sequential  execution.  Executing  a  series  of  commands  or  pro- 
cesses, one  after  the  other. 

sequential  file.  A  file  consisting  of  records  of  various  lengths 
th&t  must  be  accessed  one  after  the  other,  starting  at  the  first 
record. 

serial.  Refers  to  transmissions  in  which  data  leaves  or  arrives 
at  a  location  or  device,  with  data  units  following  one  after  the 
other  in  space  or  time. 

Setstat.  An  OS-9  routine  that  sets  (changes)  the  state  or  sta- 
tus of  a  specific  system  operation. 

sheU.  The  command  interpreter. 

sibling.   One  of  two  or  more  processes  executed  by  the  same 

parent  process. 

sign  bit.  The  leftmost  bit  of  a  binary  number  that  serves  as  an 
indicator  to  show  whether  the  nixmb^  is  positive  or  negative. 
Normally,  a  value  of  0  indicates  positive,  and  a  1  indicates 

negative. 

signal.  An  interrupt  from  the  system  or  another  process  that 
clmnges  a  procedure's  or  a  devioe^s  state.  Ear  example,  signals 

set  an  active  process  to  a  waiting  state,  awaken  an  inactive  or 
sleeping  process,  or  change  the  display  window. 

single  step.  A  procedure  in  the  Debug  mode  that  lets  you  exe- 
cute one  procedure  statement  and  (optionally)  view  the  results. 

single-user  file.   A  file  that  only  one  person  can  access  at  a 

time. 

single-user  module.  A  program  that  only  one  person  can  use 
at  a  time. 

sleeping  state.  A  si$iialion  vAme  you  or  the  ^stem  susp@ads 
a  process  for  a  specified  time  or  until  you  or  the  system  sends  it 
a  wakeup  signal. 

source  code.  Program  code  produced  using  a  computer  lan- 
guage. Before  it  can  control  a  computer,  source  code  must  be 
translated  into  machine  language,  either  by  a  compiler  or  a 
translator  program.  See  also  compiler. 
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stack.  A  storage  area  in  your  computer's  memory  in  which 
data  can  be  placed  or  recovered  in  sequence,  from  one  end  only. 

standard  error  path.  The  route  through  which  your  computer 
sends  error  codes  and  other  messages  to  the  screen. 

standard  input  path.   The  route  through  which  you  can  smd 

data  to  your  computer  (usually  the  keyboard). 

standyiKd  Qiitput  path.  The  route  your  computer  uses  to  send 
data  to  -itm  'm^mn, 

start  up.  To  turn  on  your  computer  and  initialize  OS-9. 

stop  bits.  One  or  two  bits  that  a  terminal  program  sends  after 
each  unit  of  data  to  indicate  that  the  transmission  of  the  unit  is 
complete. 

string.    A  group  of  alphanumeric  characters. 

string  data  type.  A  type  of  variable  that  can  contain  one  or 
more  ASCII  values  (values  representing  alphanumeric  characters 
or  other  symbols).  String  data  types  can  be  any  length,  up  to  the 
capacity  of  your  computer's  mnH&Xy, 

structured  programming.  BuiMing  a  program  out  d  b.  smeim 
of  procedures,  each  of  which  performs  a  specific  task  but  com- 
bines with  its  associated  procedures  as  one  program. 

subdirectory.  A  directory  that  resides  within  another  (parent) 
directory. 

subroutine.  An  operation  that  performs  a  specific  task  as  part 
of  a  laxgm:  operation. 

super  user.  The  system  user  who  has  control  of  the  entire  sys- 
tem and  access  to  all  system  files  and  modules.  User  Number  0. 

symbolic  debugging.   An  error  correcting  system  that  lets  you 

pause  program  execution  and  view  the  current  values  of  vari- 
ables, using  their  program  names. 

syntax.  The  rules  for  forming  legal  instructions  for  your 
c(snputer. 

system.  (1)  A  group  of  files  and  programs  that  provide  you 
with  control  over  your  computer,  (2)  Your  computer  with  all  its 
attached  devices. 


OS -9  Glossary 


system  call.  Built-in  OS-9  routines  that  perform  particular 
fOQctkois,  such  as  accessing  disk  files,  printing  data  on  the 
mamxi,  arid  so  on. 

data  to  be  nm&  hs'  a  process  or  fmmMnm. 

titiEAu  A  tmit  of  woiEk  pesrfbrmed  hy  ^am  eWipiit^w 

terminal.  A  computer  or  an  electronic  devi^,  ^th  a  screen 
and  keyboard,  connected  to  your  Color  Computer  3.  You  can 
access  OS-9  functions  from  a  terminal  in  the  same  manner  as 
you  can  access  them  from  your  Color  Computer  3  keyboard. 

text  files.  Files  containing  printable  characters,  or  the  code 
representing  such  characters. 

text  sereexi.  A  Type  1  or  2  screen.  Text  screens  nse  hardware 

generation  of  characters  (fonts  are  not  definable)  and  are  often 
referred  to  as  hardware  screens  or  windows.  Text  screens  cannot 
display  graphics.  Text  operations  occur  &st^  in  text  windows/ 
screens  than  on  graphic  windows/screens. 

text  window.   Any  window  created  on  a  hardware  text  screen. 

time  slice.  The  p^iod  of  time  between  system  clock  ticks.  A 
tick  occurs  every  l/60th  ©f  a  se&mi. 

timesharing.  A  i^tmation  in  wMdi  more  than  one  person  iases 
the  same  ^iH^alia^  s^tem. 


token.  In  the  BASIC  language,  a  numeric  value  that  represents 
a  keyword. 

trace.  To  display  each  procedure  statement  as  it  executes  and 
view  its  results. 

tracks.  Magnetiealty  created  concentric  circles  created  on  a 
disk  for  the  storage  of  data.  Tracks  are  established  when  you  for- 
mat a  dijii. 

transpari^t  cbiiracters.  CbM^m^sms  that  display  ov^  s^«m 
images  without  erasing  any  of  the  area  surrounding  the 

characters. 

unlink.  To  remove  a  module  (program)  from  your  computer's 
memory. 

update  mode.  The  condition  of  a  file  when  it  is  open  for  bcd^h 
reading  cmd  writing. 
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user  ID.  A  nwinber  that  identifies  the  operator  to  which  a  pro- 
cess belongs. 

user  number.   See  user  ID. 

utility.  A  short  program  that  performs  a  frequently  required 
■tsAj  miswUy  fe  the  maintenance  of  your  ©i6»aa|itttpe  Sfttem  or 
files. 

variable.  A  unit  of  storage  with  no  fixed  value.  You  define  a 
variable  and  locate  it  in  your  computer's  memory  using  a  vari- 
able name. 

VDG,   VMeo  Display  Graphics. 

vector.  A  graphics  line  or  poition  of  a  line. 

v«ify.  lb  check  data  for  accuracy. 

wait  state.  A  situation  in  which  a  process  remains  suspended 
imtil  one  of  its  child  processes  terminates  or  until  it  receives  a 
wakeup  signal  from  the  s^^ma. 

vmkm  up.       mmMem  the  execution  of  a  process  that  has  been 

sugpmM.. 


wild  card.   A  symbol  that  represents  of  takes  the  place  of  am 

or  more  other  characters  or  symbols. 

WINDINT.   Window  interface. 

window.  All  or  a  portion  of  your  video  screen  with  specific  for- 
mats (columns,  lines,  size,  colors,  and  so  on)  and  type  (graphics, 
text,  or  both).  An  area  of  a  screen  in  which  you  can  run  a  pro- 
cess or  which  can  receive  input. 

word  length.   The  number  of  bits  to  transmit  as  one  unit. 

workspace.  A  portion  of  your  computer's  memory  that 
BASIC09  establishes  for  the  storage  and  manipulation  of 

procedures. 

write.  To  transfer  data  from  the  computer's  memory  to  a 
device. 

write  permit.   %stem  permission  to  change  the  data  in  a  file. 

write  protect.  A  method  of  protecting  a  diskette  so  that  your 
computer  cannot  change  the  data  on  it. 
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